| 1 | \input texinfo |
| 2 | @c Notes to self regarding line handling: |
| 3 | @c |
| 4 | @c Empty lines are often significant before @end directives; avoid them. |
| 5 | @c |
| 6 | @c Empty lines before and after @example directives are significant in |
| 7 | @c info output but not in TeX. Empty lines inside @example directives |
| 8 | @c are significant. |
| 9 | |
| 10 | @c Conventions for formatting examples: |
| 11 | @c o If the example contains empty lines then put the surrounding empty |
| 12 | @c lines inside the @example directives. Put them outside otherwise. |
| 13 | @c o Use @group inside the example only if it shows indentation where |
| 14 | @c the relation between lines inside is relevant. |
| 15 | @c o Format line number columns like this: |
| 16 | @c 1: foo |
| 17 | @c 2: bar |
| 18 | @c ^ one space |
| 19 | @c ^^ two columns, right alignment |
| 20 | @c o Check line lengths in TeX output; they can typically be no longer |
| 21 | @c than 70 chars, 60 if the paragraph is indented. |
| 22 | |
| 23 | @comment TBD: Document the finer details of statement anchoring? |
| 24 | |
| 25 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 26 | @comment %**start of header (This is for running Texinfo on a region) |
| 27 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 28 | |
| 29 | |
| 30 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 31 | @comment How to make the various output formats: |
| 32 | @comment (Thanks to Robert Chassell for supplying this information.) |
| 33 | @comment Note that Texinfo 4.7 (or later) is needed. |
| 34 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 35 | @ignore |
| 36 | In each of the following pairs of commands, the first generates a |
| 37 | version with cross references pointing to the GNU Emacs manuals, |
| 38 | the second with them pointing to the XEmacs manuals. |
| 39 | ## Info output |
| 40 | makeinfo cc-mode.texi |
| 41 | makeinfo -DXEMACS cc-mode.texi |
| 42 | |
| 43 | ## DVI output |
| 44 | ## You may need to set up the environment variable TEXINPUTS so |
| 45 | ## that tex can find the file texinfo.tex - See the tex |
| 46 | ## manpage. |
| 47 | texi2dvi cc-mode.texi |
| 48 | texi2dvi -t "@set XEMACS " cc-mode.texi |
| 49 | |
| 50 | ## HTML output. (The --no-split parameter is optional) |
| 51 | makeinfo --html --no-split cc-mode.texi |
| 52 | makeinfo --html --no-split -DXEMACS cc-mode.texi |
| 53 | |
| 54 | ## Plain text output |
| 55 | makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ |
| 56 | --no-headers --output=cc-mode.txt cc-mode.texi |
| 57 | makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ |
| 58 | --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi |
| 59 | |
| 60 | ## DocBook output |
| 61 | makeinfo --docbook --no-split --paragraph-indent=0 \ |
| 62 | cc-mode.texi |
| 63 | makeinfo --docbook --no-split --paragraph-indent=0 \ |
| 64 | -DXEMACS cc-mode.texi |
| 65 | |
| 66 | ## XML output |
| 67 | makeinfo --xml --no-split --paragraph-indent=0 \ |
| 68 | cc-mode.texi |
| 69 | makeinfo --xml --no-split --paragraph-indent=0 \ |
| 70 | -DXEMACS cc-mode.texi |
| 71 | |
| 72 | #### (You must be in the same directory as the viewed file.) |
| 73 | |
| 74 | ## View DVI output |
| 75 | xdvi cc-mode.dvi & |
| 76 | |
| 77 | ## View HTML output |
| 78 | mozilla cc-mode.html |
| 79 | @end ignore |
| 80 | |
| 81 | @comment No overfull hbox marks in the dvi file. |
| 82 | @finalout |
| 83 | |
| 84 | @setfilename ../../info/ccmode |
| 85 | @settitle CC Mode Manual |
| 86 | @footnotestyle end |
| 87 | |
| 88 | @c The following four macros generate the filenames and titles of the |
| 89 | @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the |
| 90 | @c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it |
| 91 | @c to generate an XEmacs version, e.g. with |
| 92 | @c "makeinfo -DXEMACS cc-mode.texi". |
| 93 | @ifset XEMACS |
| 94 | @macro emacsman |
| 95 | xemacs |
| 96 | @end macro |
| 97 | @macro emacsmantitle |
| 98 | XEmacs User's Manual |
| 99 | @end macro |
| 100 | @macro lispref |
| 101 | lispref |
| 102 | @end macro |
| 103 | @macro lispreftitle |
| 104 | XEmacs Lisp Reference Manual |
| 105 | @end macro |
| 106 | @end ifset |
| 107 | |
| 108 | @ifclear XEMACS |
| 109 | @macro emacsman |
| 110 | emacs |
| 111 | @end macro |
| 112 | @macro emacsmantitle |
| 113 | GNU Emacs Manual |
| 114 | @end macro |
| 115 | @macro lispref |
| 116 | elisp |
| 117 | @end macro |
| 118 | @macro lispreftitle |
| 119 | GNU Emacs Lisp Reference Manual |
| 120 | @end macro |
| 121 | @end ifclear |
| 122 | |
| 123 | |
| 124 | @macro ccmode |
| 125 | CC Mode |
| 126 | @end macro |
| 127 | |
| 128 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 129 | @comment @setchapternewpage odd !! we don't want blank pages !! |
| 130 | @comment %**end of header (This is for running Texinfo on a region) |
| 131 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 132 | |
| 133 | |
| 134 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 135 | @comment |
| 136 | @comment Texinfo manual for CC Mode |
| 137 | @comment Generated from the original README file by Krishna Padmasola |
| 138 | @comment <krishna@earth-gw.njit.edu> |
| 139 | @comment |
| 140 | @comment Authors: |
| 141 | @comment Barry A. Warsaw |
| 142 | @comment Martin Stjernholm |
| 143 | @comment Alan Mackenzie |
| 144 | @comment |
| 145 | @comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org> |
| 146 | @comment |
| 147 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 148 | |
| 149 | @comment Define an index for syntactic symbols. |
| 150 | @ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss |
| 151 | @c For Info, unlike tex, @syncodeindex needs a matching @defindex. |
| 152 | @defindex ss |
| 153 | @end ifnottex |
| 154 | |
| 155 | @comment Combine key, syntactic symbol and concept indices into one. |
| 156 | @syncodeindex ss cp |
| 157 | @syncodeindex ky cp |
| 158 | |
| 159 | @copying |
| 160 | This manual is for CC Mode in Emacs. |
| 161 | |
| 162 | Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, |
| 163 | 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. |
| 164 | |
| 165 | @quotation |
| 166 | Permission is granted to copy, distribute and/or modify this document |
| 167 | under the terms of the GNU Free Documentation License, Version 1.2 or |
| 168 | any later version published by the Free Software Foundation; with the |
| 169 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and |
| 170 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU |
| 171 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
| 172 | license is included in the section entitled ``GNU Free Documentation |
| 173 | License'' in the Emacs manual. |
| 174 | |
| 175 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
| 176 | this GNU Manual, like GNU software. Copies published by the Free |
| 177 | Software Foundation raise funds for GNU development.'' |
| 178 | |
| 179 | This document is part of a collection distributed under the GNU Free |
| 180 | Documentation License. If you want to distribute this document |
| 181 | separately from the collection, you can do so by adding a copy of the |
| 182 | license to the document, as described in section 6 of the license. |
| 183 | @end quotation |
| 184 | @end copying |
| 185 | |
| 186 | @comment Info directory entry for use by install-info. The indentation |
| 187 | @comment here is by request from the FSF folks. |
| 188 | @dircategory Emacs |
| 189 | @direntry |
| 190 | * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, |
| 191 | Java, Pike, AWK, and CORBA IDL code. |
| 192 | @end direntry |
| 193 | |
| 194 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 195 | @comment TeX title page |
| 196 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 197 | |
| 198 | @titlepage |
| 199 | @sp 10 |
| 200 | |
| 201 | @center @titlefont{CC Mode 5.31} |
| 202 | @sp 2 |
| 203 | @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} |
| 204 | @sp 2 |
| 205 | @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie |
| 206 | |
| 207 | @page |
| 208 | @vskip 0pt plus 1filll |
| 209 | @insertcopying |
| 210 | |
| 211 | This manual was generated from cc-mode.texi, which can be downloaded |
| 212 | from |
| 213 | @url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/doc/misc/cc-mode.texi}. |
| 214 | @end titlepage |
| 215 | |
| 216 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 217 | @comment The Top node contains the master menu for the Info file. |
| 218 | @comment This appears only in the Info file, not the printed manual. |
| 219 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 220 | |
| 221 | @node Top, Introduction, (dir), (dir) |
| 222 | @comment node-name, next, previous, up |
| 223 | |
| 224 | @ifinfo |
| 225 | @top @ccmode{} |
| 226 | |
| 227 | @ccmode{} is a GNU Emacs mode for editing files containing C, C++, |
| 228 | Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike |
| 229 | and AWK code. It provides syntax-based indentation, font locking, and |
| 230 | has several handy commands and some minor modes to make the editing |
| 231 | easier. It does not provide tools to look up and navigate between |
| 232 | functions, classes etc - there are other packages for that. |
| 233 | @end ifinfo |
| 234 | |
| 235 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 236 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 237 | |
| 238 | @menu |
| 239 | * Introduction:: |
| 240 | * Overview:: |
| 241 | * Getting Started:: |
| 242 | * Commands:: |
| 243 | * Font Locking:: |
| 244 | * Config Basics:: |
| 245 | * Custom Filling and Breaking:: |
| 246 | * Custom Auto-newlines:: |
| 247 | * Clean-ups:: |
| 248 | * Indentation Engine Basics:: |
| 249 | * Customizing Indentation:: |
| 250 | * Custom Macros:: |
| 251 | * Odds and Ends:: |
| 252 | * Sample .emacs File:: |
| 253 | * Performance Issues:: |
| 254 | * Limitations and Known Bugs:: |
| 255 | * FAQ:: |
| 256 | * Updating CC Mode:: |
| 257 | * Mailing Lists and Bug Reports:: |
| 258 | * GNU Free Documentation License:: |
| 259 | * Command and Function Index:: |
| 260 | * Variable Index:: |
| 261 | * Concept and Key Index:: |
| 262 | |
| 263 | @detailmenu |
| 264 | --- The Detailed Node Listing --- |
| 265 | |
| 266 | Commands |
| 267 | |
| 268 | * Indentation Commands:: |
| 269 | * Comment Commands:: |
| 270 | * Movement Commands:: |
| 271 | * Filling and Breaking:: |
| 272 | * Minor Modes:: |
| 273 | * Electric Keys:: |
| 274 | * Auto-newlines:: |
| 275 | * Hungry WS Deletion:: |
| 276 | * Subword Movement:: |
| 277 | * Other Commands:: |
| 278 | |
| 279 | Font Locking |
| 280 | |
| 281 | * Font Locking Preliminaries:: |
| 282 | * Faces:: |
| 283 | * Doc Comments:: |
| 284 | * AWK Mode Font Locking:: |
| 285 | |
| 286 | Configuration Basics |
| 287 | |
| 288 | * CC Hooks:: |
| 289 | * Style Variables:: |
| 290 | * Styles:: |
| 291 | |
| 292 | Styles |
| 293 | |
| 294 | * Built-in Styles:: |
| 295 | * Choosing a Style:: |
| 296 | * Adding Styles:: |
| 297 | * File Styles:: |
| 298 | |
| 299 | Customizing Auto-newlines |
| 300 | |
| 301 | * Hanging Braces:: |
| 302 | * Hanging Colons:: |
| 303 | * Hanging Semicolons and Commas:: |
| 304 | |
| 305 | Hanging Braces |
| 306 | |
| 307 | * Custom Braces:: |
| 308 | |
| 309 | Indentation Engine Basics |
| 310 | |
| 311 | * Syntactic Analysis:: |
| 312 | * Syntactic Symbols:: |
| 313 | * Indentation Calculation:: |
| 314 | |
| 315 | Syntactic Symbols |
| 316 | |
| 317 | * Function Symbols:: |
| 318 | * Class Symbols:: |
| 319 | * Conditional Construct Symbols:: |
| 320 | * Switch Statement Symbols:: |
| 321 | * Brace List Symbols:: |
| 322 | * External Scope Symbols:: |
| 323 | * Paren List Symbols:: |
| 324 | * Literal Symbols:: |
| 325 | * Multiline Macro Symbols:: |
| 326 | * Objective-C Method Symbols:: |
| 327 | * Anonymous Class Symbol:: |
| 328 | * Statement Block Symbols:: |
| 329 | * K&R Symbols:: |
| 330 | |
| 331 | Customizing Indentation |
| 332 | |
| 333 | * c-offsets-alist:: |
| 334 | * Interactive Customization:: |
| 335 | * Line-Up Functions:: |
| 336 | * Custom Line-Up:: |
| 337 | * Other Indentation:: |
| 338 | |
| 339 | Line-Up Functions |
| 340 | |
| 341 | * Brace/Paren Line-Up:: |
| 342 | * List Line-Up:: |
| 343 | * Operator Line-Up:: |
| 344 | * Comment Line-Up:: |
| 345 | * Misc Line-Up:: |
| 346 | |
| 347 | @end detailmenu |
| 348 | @end menu |
| 349 | |
| 350 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 351 | @node Introduction, Overview, Top, Top |
| 352 | @comment node-name, next, previous, up |
| 353 | @chapter Introduction |
| 354 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 355 | |
| 356 | @cindex BOCM |
| 357 | @cindex history |
| 358 | @cindex awk-mode.el |
| 359 | @cindex c-mode.el |
| 360 | @cindex c++-mode.el |
| 361 | |
| 362 | Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, |
| 363 | C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and |
| 364 | CIDL), Pike and AWK code. This incarnation of the mode is descended |
| 365 | from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM |
| 366 | @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been |
| 367 | maintaining since 1992, and @file{awk-mode.el}, a long neglected mode |
| 368 | in the (X)Emacs base. |
| 369 | |
| 370 | Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} |
| 371 | Maintainers Team, and implemented the Pike support. In 2000 Martin |
| 372 | took over as the sole maintainer. In 2001 Alan Mackenzie joined the |
| 373 | team, implementing AWK support in version 5.30. @ccmode{} did not |
| 374 | originally contain the font lock support for its languages --- that |
| 375 | was added in version 5.30. |
| 376 | |
| 377 | This manual describes @ccmode{} |
| 378 | @comment The following line must appear on its own, so that the |
| 379 | version 5.31. |
| 380 | @comment Release.py script can update the version number automatically |
| 381 | |
| 382 | @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, |
| 383 | Java, CORBA's Interface Definition Language, Pike@footnote{A C-like |
| 384 | scripting language with its roots in the LPC language used in some MUD |
| 385 | engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this |
| 386 | way, you can easily set up consistent font locking and coding styles for |
| 387 | use in editing all of these languages, although AWK is not yet as |
| 388 | uniformly integrated as the other languages. |
| 389 | |
| 390 | @findex c-mode |
| 391 | @findex c++-mode |
| 392 | @findex objc-mode |
| 393 | @findex java-mode |
| 394 | @findex idl-mode |
| 395 | @findex pike-mode |
| 396 | @findex awk-mode |
| 397 | Note that the name of this package is ``@ccmode{}'', but there is no top |
| 398 | level @code{cc-mode} entry point. All of the variables, commands, and |
| 399 | functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and |
| 400 | @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, |
| 401 | @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are |
| 402 | provided. This package is intended to be a replacement for |
| 403 | @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. |
| 404 | |
| 405 | A special word of thanks goes to Krishna Padmasola for his work in |
| 406 | converting the original @file{README} file to Texinfo format. I'd |
| 407 | also like to thank all the @ccmode{} victims who help enormously |
| 408 | during the early beta stages of @ccmode{}'s development. |
| 409 | |
| 410 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 411 | @node Overview, Getting Started, Introduction, Top |
| 412 | @comment node-name, next, previous, up@cindex organization of the manual |
| 413 | @chapter Overview of the Manual |
| 414 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 415 | |
| 416 | @noindent |
| 417 | The manual starts with several introductory chapters (including this |
| 418 | one). |
| 419 | |
| 420 | @noindent |
| 421 | The next chunk of the manual describes the day to day @emph{use} of |
| 422 | @ccmode{} (as contrasted with how to customize it). |
| 423 | |
| 424 | @itemize @bullet |
| 425 | @item |
| 426 | The chapter ``Commands'' describes in detail how to use (nearly) all |
| 427 | of @ccmode{}'s features. There are extensive cross-references from |
| 428 | here to the corresponding sections later in the manual which tell you |
| 429 | how to customize these features. |
| 430 | |
| 431 | @item |
| 432 | ``Font Locking'' describes how ``syntax highlighting'' is applied to |
| 433 | your buffers. It is mainly background information and can be skipped |
| 434 | over at a first reading. |
| 435 | @end itemize |
| 436 | |
| 437 | @noindent |
| 438 | The next chunk of the manual describes how to @emph{customize} |
| 439 | @ccmode{}. Typically, an overview of a topic is given at the chapter |
| 440 | level, then the sections and subsections describe the material in |
| 441 | increasing detail. |
| 442 | |
| 443 | @itemize @bullet |
| 444 | @item |
| 445 | The chapter ``Configuration Basics'' tells you @emph{how} to write |
| 446 | customizations - whether in hooks, in styles, in both, or in neither, |
| 447 | depending on your needs. It describes the @ccmode{} style system and |
| 448 | lists the standard styles that @ccmode{} supplies. |
| 449 | |
| 450 | @item |
| 451 | The next few chapters describe in detail how to customize the various |
| 452 | features of @ccmode{}. |
| 453 | |
| 454 | @item |
| 455 | Finally, there is a sample @file{.emacs} fragment, which might help you |
| 456 | in creating your own customization. |
| 457 | @end itemize |
| 458 | |
| 459 | @noindent |
| 460 | The manual ends with ``this and that'', things that don't fit cleanly |
| 461 | into any of the previous chunks. |
| 462 | |
| 463 | @itemize @bullet |
| 464 | @item |
| 465 | Two chapters discuss the performance of @ccmode{} and known |
| 466 | bugs/limitations. |
| 467 | |
| 468 | @item |
| 469 | The FAQ contains a list of common problems and questions. |
| 470 | |
| 471 | @item |
| 472 | The next two chapters tell you how to get in touch with the @ccmode{} |
| 473 | project - whether for updating @ccmode{} or submitting bug reports. |
| 474 | @end itemize |
| 475 | |
| 476 | @noindent |
| 477 | Finally, there are the customary indices. |
| 478 | |
| 479 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 480 | @node Getting Started, Commands, Overview, Top |
| 481 | @comment node-name, next, previous, up |
| 482 | @chapter Getting Started |
| 483 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 484 | |
| 485 | If you got this version of @ccmode{} with Emacs or XEmacs, it should |
| 486 | work just fine right out of the box. Note however that you might not |
| 487 | have the latest @ccmode{} release and might want to upgrade your copy |
| 488 | (see below). |
| 489 | |
| 490 | You should probably start by skimming through the entire chapter |
| 491 | @ref{Commands} to get an overview of @ccmode{}'s capabilities. |
| 492 | |
| 493 | After trying out some commands, you may dislike some aspects of |
| 494 | @ccmode{}'s default configuration. Here is an outline of how to |
| 495 | change some of the settings that newcomers to @ccmode{} most often |
| 496 | want to change: |
| 497 | |
| 498 | @table @asis |
| 499 | @item c-basic-offset |
| 500 | This Lisp variable holds an integer, the number of columns @ccmode{} |
| 501 | indents nested code. To set this value to 6, customize |
| 502 | @code{c-basic-offset} or put this into your @file{.emacs}: |
| 503 | |
| 504 | @example |
| 505 | (setq c-basic-offset 6) |
| 506 | @end example |
| 507 | |
| 508 | @item The (indentation) style |
| 509 | The basic ``shape'' of indentation created by @ccmode{}---by default, |
| 510 | this is @code{gnu} style (except for Java and AWK buffers). A list of |
| 511 | the available styles and their descriptions can be found in |
| 512 | @ref{Built-in Styles}. A complete specification of the @ccmode{} |
| 513 | style system, including how to create your own style, can be found in |
| 514 | the chapter @ref{Styles}. To set your style to @code{linux}, either |
| 515 | customize @code{c-default-style} or put this into your @file{.emacs}: |
| 516 | |
| 517 | @example |
| 518 | (setq c-default-style '((java-mode . "java") |
| 519 | (awk-mode . "awk") |
| 520 | (other . "linux"))) |
| 521 | @end example |
| 522 | |
| 523 | @item Electric Indentation |
| 524 | Normally, when you type ``punctuation'' characters such as @samp{;} or |
| 525 | @samp{@{}, @ccmode{} instantly reindents the current line. This can |
| 526 | be disconcerting until you get used to it. To disable @dfn{electric |
| 527 | indentation} in the current buffer, type @kbd{C-c C-l}. Type the same |
| 528 | thing to enable it again. To have electric indentation disabled by |
| 529 | default, put the following into your @file{.emacs} file@footnote{There |
| 530 | is no ``easy customization'' facility for making this change.}: |
| 531 | |
| 532 | @example |
| 533 | (setq-default c-electric-flag nil) |
| 534 | @end example |
| 535 | |
| 536 | @noindent |
| 537 | Details of this and other similar ``Minor Modes'' appear in the |
| 538 | section @ref{Minor Modes}. |
| 539 | |
| 540 | @item Making the @key{RET} key indent the new line |
| 541 | The standard Emacs binding for @key{RET} just adds a new line. If you |
| 542 | want it to reindent the new line as well, rebind the key. Note that |
| 543 | the action of rebinding would fail if the pertinent keymap didn't yet |
| 544 | exist---we thus need to delay the action until after @ccmode{} has |
| 545 | been loaded. Put the following code into your @file{.emacs}: |
| 546 | |
| 547 | @example |
| 548 | (defun my-make-CR-do-indent () |
| 549 | (define-key c-mode-base-map "\C-m" 'c-context-line-break)) |
| 550 | (add-hook 'c-initialization-hook 'my-make-CR-do-indent) |
| 551 | @end example |
| 552 | |
| 553 | @noindent |
| 554 | This example demonstrates the use of a very powerful @ccmode{} (and |
| 555 | Emacs) facility, the hook. The use of @ccmode{}'s hooks is described |
| 556 | in @ref{CC Hooks}. |
| 557 | @end table |
| 558 | |
| 559 | All these settings should occur in your @file{.emacs} @emph{before} |
| 560 | any @ccmode{} buffers get loaded---in particular, before any call of |
| 561 | @code{desktop-read}. |
| 562 | |
| 563 | As you get to know the mode better, you may want to make more |
| 564 | ambitious changes to your configuration. For this, you should start |
| 565 | reading the chapter @ref{Config Basics}. |
| 566 | |
| 567 | If you are upgrading an existing @ccmode{} installation, please see |
| 568 | the @file{README} file for installation details. In particular, if |
| 569 | you are going to be editing AWK files, @file{README} describes how to |
| 570 | configure your (X)Emacs so that @ccmode{} will supersede the obsolete |
| 571 | @code{awk-mode.el} which might have been supplied with your (X)Emacs. |
| 572 | @ccmode{} might not work with older versions of Emacs or XEmacs. See |
| 573 | the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} |
| 574 | for the latest information on Emacs version and package compatibility |
| 575 | (@pxref{Updating CC Mode}). |
| 576 | |
| 577 | @deffn Command c-version |
| 578 | @findex version (c-) |
| 579 | You can find out what version of @ccmode{} you are using by visiting a C |
| 580 | file and entering @kbd{M-x c-version RET}. You should see this message in |
| 581 | the echo area: |
| 582 | |
| 583 | @example |
| 584 | Using CC Mode version 5.XX |
| 585 | @end example |
| 586 | |
| 587 | @noindent |
| 588 | where @samp{XX} is the minor release number. |
| 589 | @end deffn |
| 590 | |
| 591 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 592 | @node Commands, Font Locking, Getting Started, Top |
| 593 | @comment node-name, next, previous, up |
| 594 | @chapter Commands |
| 595 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 596 | |
| 597 | This chapter specifies all of CC Mode's commands, and thus contains |
| 598 | nearly everything you need to know to @emph{use} @ccmode{} (as |
| 599 | contrasted with configuring it). @dfn{Commands} here means both |
| 600 | control key sequences and @dfn{electric keys}, these being characters |
| 601 | such as @samp{;} which, as well as inserting themselves into the |
| 602 | buffer, also do other things. |
| 603 | |
| 604 | You might well want to review |
| 605 | @ifset XEMACS |
| 606 | @ref{Lists,,,@emacsman{}, @emacsmantitle{}}, |
| 607 | @end ifset |
| 608 | @ifclear XEMACS |
| 609 | @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, |
| 610 | @end ifclear |
| 611 | which describes commands for moving around brace and parenthesis |
| 612 | structures. |
| 613 | |
| 614 | |
| 615 | @menu |
| 616 | * Indentation Commands:: |
| 617 | * Comment Commands:: |
| 618 | * Movement Commands:: |
| 619 | * Filling and Breaking:: |
| 620 | * Minor Modes:: |
| 621 | * Electric Keys:: |
| 622 | * Auto-newlines:: |
| 623 | * Hungry WS Deletion:: |
| 624 | * Subword Movement:: |
| 625 | * Other Commands:: |
| 626 | @end menu |
| 627 | |
| 628 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 629 | @node Indentation Commands, Comment Commands, Commands, Commands |
| 630 | @comment node-name, next, previous,up |
| 631 | @section Indentation Commands |
| 632 | @cindex indentation |
| 633 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 634 | |
| 635 | The following commands reindent C constructs. Note that when you |
| 636 | change your coding style, either interactively or through some other |
| 637 | means, your file does @emph{not} automatically get reindented. You |
| 638 | will need to execute one of the following commands to see the effects |
| 639 | of your changes. |
| 640 | |
| 641 | @cindex GNU indent program |
| 642 | Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} |
| 643 | (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is |
| 644 | formatted. Changing the ``hanginess'' of a brace and then |
| 645 | reindenting, will not move the brace to a different line. For this, |
| 646 | you're better off getting an external program like GNU @code{indent}, |
| 647 | which will rearrange brace location, amongst other things. |
| 648 | |
| 649 | Preprocessor directives are handled as syntactic whitespace from other |
| 650 | code, i.e. they can be interspersed anywhere without affecting the |
| 651 | indentation of the surrounding code, just like comments. |
| 652 | |
| 653 | The code inside macro definitions is, by default, still analyzed |
| 654 | syntactically so that you get relative indentation there just as you'd |
| 655 | get if the same code was outside a macro. However, since there is no |
| 656 | hint about the syntactic context, i.e. whether the macro expands to an |
| 657 | expression, to some statements, or perhaps to whole functions, the |
| 658 | syntactic recognition can be wrong. @ccmode{} manages to figure it |
| 659 | out correctly most of the time, though. |
| 660 | |
| 661 | Reindenting large sections of code can take a long time. When |
| 662 | @ccmode{} reindents a region of code, it is essentially equivalent to |
| 663 | hitting @key{TAB} on every line of the region. |
| 664 | |
| 665 | These commands indent code: |
| 666 | |
| 667 | @table @asis |
| 668 | @item @kbd{@key{TAB}} (@code{c-indent-command}) |
| 669 | @kindex TAB |
| 670 | @findex c-indent-command |
| 671 | @findex indent-command (c-) |
| 672 | This command indents the current line. That is all you need to know |
| 673 | about it for normal use. |
| 674 | |
| 675 | @code{c-indent-command} does different things, depending on the |
| 676 | setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine |
| 677 | Basics}): |
| 678 | |
| 679 | @itemize @bullet |
| 680 | @item |
| 681 | When it's non-@code{nil} (which it normally is), the command indents |
| 682 | the line according to its syntactic context. With a prefix argument |
| 683 | (@kbd{C-u @key{TAB}}), it will re-indent the entire |
| 684 | expression@footnote{this is only useful for a line starting with a |
| 685 | comment opener or an opening brace, parenthesis, or string quote.} |
| 686 | that begins at the line's left margin. |
| 687 | |
| 688 | @item |
| 689 | When it's @code{nil}, the command indents the line by an extra |
| 690 | @code{c-basic-offset} columns. A prefix argument acts as a |
| 691 | multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, |
| 692 | removing @code{c-basic-offset} columns from the indentation. |
| 693 | @end itemize |
| 694 | |
| 695 | The precise behavior is modified by several variables: With |
| 696 | @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace |
| 697 | in some circumstances---@code{c-insert-tab-function} then defines |
| 698 | precisely what sort of ``whitespace'' this will be. Set the standard |
| 699 | Emacs variable @code{indent-tabs-mode} to @code{t} if you want real |
| 700 | @samp{tab} characters to be used in the indentation, to @code{nil} if |
| 701 | you want only spaces. @xref{Just Spaces,,, @emacsman{}, |
| 702 | @emacsmantitle{}}. |
| 703 | |
| 704 | @defopt c-tab-always-indent |
| 705 | @vindex tab-always-indent (c-) |
| 706 | @cindex literal |
| 707 | This variable modifies how @key{TAB} operates. |
| 708 | @itemize @bullet |
| 709 | @item |
| 710 | When it is @code{t} (the default), @key{TAB} simply indents the |
| 711 | current line. |
| 712 | @item |
| 713 | When it is @code{nil}, @key{TAB} (re)indents the line only if point is |
| 714 | to the left of the first non-whitespace character on the line. |
| 715 | Otherwise it inserts some whitespace (a tab or an equivalent number of |
| 716 | spaces - see below) at point. |
| 717 | @item |
| 718 | With some other value, the line is reindented. Additionally, if point |
| 719 | is within a string or comment, some whitespace is inserted. |
| 720 | @end itemize |
| 721 | @end defopt |
| 722 | |
| 723 | @defopt c-insert-tab-function |
| 724 | @vindex insert-tab-function (c-) |
| 725 | @findex tab-to-tab-stop |
| 726 | When ``some whitespace'' is inserted as described above, what actually |
| 727 | happens is that the function stored in @code{c-insert-tab-function} is |
| 728 | called. Normally, this is @code{insert-tab}, which inserts a real tab |
| 729 | character or the equivalent number of spaces (depending on |
| 730 | @code{indent-tabs-mode}). Some people, however, set |
| 731 | @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get |
| 732 | hard tab stops when indenting. |
| 733 | @end defopt |
| 734 | @end table |
| 735 | |
| 736 | @noindent |
| 737 | The kind of indentation the next five commands do depends on the |
| 738 | setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine |
| 739 | Basics}): |
| 740 | @itemize @bullet |
| 741 | @item |
| 742 | when it is non-@code{nil} (the default), the commands indent lines |
| 743 | according to their syntactic context; |
| 744 | @item |
| 745 | when it is @code{nil}, they just indent each line the same amount as |
| 746 | the previous non-blank line. The commands that indent a region aren't |
| 747 | very useful in this case. |
| 748 | @end itemize |
| 749 | |
| 750 | @table @asis |
| 751 | @item @kbd{C-j} (@code{newline-and-indent}) |
| 752 | @kindex C-j |
| 753 | @findex newline-and-indent |
| 754 | Inserts a newline and indents the new blank line, ready to start |
| 755 | typing. This is a standard (X)Emacs command. |
| 756 | |
| 757 | @item @kbd{C-M-q} (@code{c-indent-exp}) |
| 758 | @kindex C-M-q |
| 759 | @findex c-indent-exp |
| 760 | @findex indent-exp (c-) |
| 761 | Indents an entire balanced brace or parenthesis expression. Note that |
| 762 | point must be on the opening brace or parenthesis of the expression |
| 763 | you want to indent. |
| 764 | |
| 765 | @item @kbd{C-c C-q} (@code{c-indent-defun}) |
| 766 | @kindex C-c C-q |
| 767 | @findex c-indent-defun |
| 768 | @findex indent-defun (c-) |
| 769 | Indents the entire top-level function, class or macro definition |
| 770 | encompassing point. It leaves point unchanged. This function can't be |
| 771 | used to reindent a nested brace construct, such as a nested class or |
| 772 | function, or a Java method. The top-level construct being reindented |
| 773 | must be complete, i.e. it must have both a beginning brace and an ending |
| 774 | brace. |
| 775 | |
| 776 | @item @kbd{C-M-\} (@code{indent-region}) |
| 777 | @kindex C-M-\ |
| 778 | @findex indent-region |
| 779 | Indents an arbitrary region of code. This is a standard Emacs command, |
| 780 | tailored for C code in a @ccmode{} buffer. Note, of course, that point |
| 781 | and mark must delineate the region you want to indent. |
| 782 | |
| 783 | @item @kbd{C-M-h} (@code{c-mark-function}) |
| 784 | @kindex C-M-h |
| 785 | @findex c-mark-function |
| 786 | @findex mark-function (c-) |
| 787 | While not strictly an indentation command, this is useful for marking |
| 788 | the current top-level function or class definition as the current |
| 789 | region. As with @code{c-indent-defun}, this command operates on |
| 790 | top-level constructs, and can't be used to mark say, a Java method. |
| 791 | @end table |
| 792 | |
| 793 | These variables are also useful when indenting code: |
| 794 | |
| 795 | @defopt indent-tabs-mode |
| 796 | This is a standard Emacs variable that controls how line indentation |
| 797 | is composed. When it's non-@code{nil}, tabs can be used in a line's |
| 798 | indentation, otherwise only spaces are used. |
| 799 | @end defopt |
| 800 | |
| 801 | @defopt c-progress-interval |
| 802 | @vindex progress-interval (c-) |
| 803 | When indenting large regions of code, this variable controls how often a |
| 804 | progress message is displayed. Set this variable to @code{nil} to |
| 805 | inhibit the progress messages, or set it to an integer which is how |
| 806 | often (in seconds) progress messages are to be displayed. |
| 807 | @end defopt |
| 808 | |
| 809 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 810 | @node Comment Commands, Movement Commands, Indentation Commands, Commands |
| 811 | @comment node-name, next, previous, up |
| 812 | @section Comment Commands |
| 813 | @cindex comments (insertion of) |
| 814 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 815 | |
| 816 | @table @asis |
| 817 | @item @kbd{C-c C-c} (@code{comment-region}) |
| 818 | @kindex C-c C-c |
| 819 | @findex comment-region |
| 820 | This command comments out the lines that start in the region. With a |
| 821 | negative argument, it does the opposite - it deletes the comment |
| 822 | delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU |
| 823 | Emacs Manual}, for fuller details. @code{comment-region} isn't |
| 824 | actually part of @ccmode{} - it is given a @ccmode{} binding for |
| 825 | convenience. |
| 826 | |
| 827 | @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) |
| 828 | @kindex M-; |
| 829 | @findex comment-dwim |
| 830 | @findex indent-for-comment |
| 831 | Insert a comment at the end of the current line, if none is there |
| 832 | already. Then reindent the comment according to @code{comment-column} |
| 833 | @ifclear XEMACS |
| 834 | (@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) |
| 835 | @end ifclear |
| 836 | @ifset XEMACS |
| 837 | (@pxref{Comments,,, xemacs, XEmacs User's Manual}) |
| 838 | @end ifset |
| 839 | and the variables below. Finally, position the point after the |
| 840 | comment starter. @kbd{C-u M-;} kills any comment on the current line, |
| 841 | together with any whitespace before it. This is a standard Emacs |
| 842 | command, but @ccmode{} enhances it a bit with two variables: |
| 843 | |
| 844 | @defopt c-indent-comment-alist |
| 845 | @vindex indent-comment-alist (c-) |
| 846 | @vindex comment-column |
| 847 | This style variable allows you to vary the column that @kbd{M-;} puts |
| 848 | the comment at, depending on what sort of code is on the line, and |
| 849 | possibly the indentation of any similar comment on the preceding line. |
| 850 | It is an association list that maps different types of lines to |
| 851 | actions describing how they should be handled. If a certain line type |
| 852 | isn't present on the list then the line is indented to the column |
| 853 | specified by @code{comment-column}. |
| 854 | |
| 855 | See the documentation string for a full description of this |
| 856 | variable (use @kbd{C-h v c-indent-comment-alist}). |
| 857 | @end defopt |
| 858 | |
| 859 | @defopt c-indent-comments-syntactically-p |
| 860 | @vindex indent-comments-syntactically-p (c-) |
| 861 | Normally, when this style variable is @code{nil}, @kbd{M-;} will |
| 862 | indent comment-only lines according to @code{c-indent-comment-alist}, |
| 863 | just as it does with lines where other code precede the comments. |
| 864 | However, if you want it to act just like @key{TAB} for comment-only |
| 865 | lines you can get that by setting |
| 866 | @code{c-indent-comments-syntactically-p} to non-@code{nil}. |
| 867 | |
| 868 | If @code{c-indent-comments-syntactically-p} is non-@code{nil} then |
| 869 | @code{c-indent-comment-alist} won't be consulted at all for comment-only |
| 870 | lines. |
| 871 | @end defopt |
| 872 | @end table |
| 873 | |
| 874 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 875 | @node Movement Commands, Filling and Breaking, Comment Commands, Commands |
| 876 | @comment node-name, next, previous, up |
| 877 | @section Movement Commands |
| 878 | @cindex movement |
| 879 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 880 | |
| 881 | @ccmode{} contains some useful commands for moving around in C code. |
| 882 | |
| 883 | @table @asis |
| 884 | @item @kbd{C-M-a} (@code{c-beginning-of-defun}) |
| 885 | @itemx @kbd{C-M-e} (@code{c-end-of-defun}) |
| 886 | @findex c-beginning-of-defun |
| 887 | @findex c-end-of-defun |
| 888 | |
| 889 | Move to the beginning or end of the current or next function. Other |
| 890 | constructs (such as a structs or classes) which have a brace block |
| 891 | also count as ``functions'' here. To move over several functions, you |
| 892 | can give these commands a repeat count. |
| 893 | |
| 894 | The start of a function is at its header. The end of the function is |
| 895 | after its closing brace, or after the semicolon of a construct (such |
| 896 | as a @code{struct}) which doesn't end at the brace. These two |
| 897 | commands try to leave point at the beginning of a line near the actual |
| 898 | start or end of the function. This occasionally causes point not to |
| 899 | move at all. |
| 900 | |
| 901 | These functions are analogous to the Emacs built-in commands |
| 902 | @code{beginning-of-defun} and @code{end-of-defun}, except they |
| 903 | eliminate the constraint that the top-level opening brace of the defun |
| 904 | must be in column zero. See @ref{Defuns,,,@emacsman{}, |
| 905 | @emacsmantitle{}}, for more information. |
| 906 | |
| 907 | @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) |
| 908 | @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) |
| 909 | @kindex C-M-a (AWK Mode) |
| 910 | @kindex C-M-e (AWK Mode) |
| 911 | @findex c-awk-beginning-of-defun |
| 912 | @findex awk-beginning-of-defun (c-) |
| 913 | @findex c-awk-end-of-defun |
| 914 | @findex awk-end-of-defun (c-) |
| 915 | Move to the beginning or end of the current or next AWK defun. These |
| 916 | commands can take prefix-arguments, their functionality being entirely |
| 917 | equivalent to @code{beginning-of-defun} and @code{end-of-defun}. |
| 918 | |
| 919 | AWK Mode @dfn{defuns} are either pattern/action pairs (either of which |
| 920 | might be implicit) or user defined functions. Having the @samp{@{} and |
| 921 | @samp{@}} (if there are any) in column zero, as is suggested for some |
| 922 | modes, is neither necessary nor helpful in AWK mode. |
| 923 | |
| 924 | @item @kbd{M-a} (@code{c-beginning-of-statement}) |
| 925 | @itemx @kbd{M-e} (@code{c-end-of-statement}) |
| 926 | @kindex M-a |
| 927 | @kindex M-e |
| 928 | @findex c-beginning-of-statement |
| 929 | @findex c-end-of-statement |
| 930 | @findex beginning-of-statement (c-) |
| 931 | @findex end-of-statement (c-) |
| 932 | Move to the beginning or end of the innermost C statement. If point |
| 933 | is already there, move to the next beginning or end of a statement, |
| 934 | even if that means moving into a block. (Use @kbd{C-M-b} or |
| 935 | @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} |
| 936 | means move over @var{n} statements. |
| 937 | |
| 938 | If point is within or next to a comment or a string which spans more |
| 939 | than one line, these commands move by sentences instead of statements. |
| 940 | |
| 941 | When called from a program, these functions take three optional |
| 942 | arguments: the repetition count, a buffer position limit which is the |
| 943 | farthest back to search for the syntactic context, and a flag saying |
| 944 | whether to do sentence motion in or near comments and multiline |
| 945 | strings. |
| 946 | |
| 947 | @item @kbd{C-c C-u} (@code{c-up-conditional}) |
| 948 | @kindex C-c C-u |
| 949 | @findex c-up-conditional |
| 950 | @findex up-conditional (c-) |
| 951 | Move back to the containing preprocessor conditional, leaving the mark |
| 952 | behind. A prefix argument acts as a repeat count. With a negative |
| 953 | argument, move forward to the end of the containing preprocessor |
| 954 | conditional. |
| 955 | |
| 956 | @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the |
| 957 | function stops at them when going backward, but not when going |
| 958 | forward. |
| 959 | |
| 960 | This key sequence is not bound in AWK Mode, which doesn't have |
| 961 | preprocessor statements. |
| 962 | |
| 963 | @item @kbd{M-x c-up-conditional-with-else} |
| 964 | @findex c-up-conditional-with-else |
| 965 | @findex up-conditional-with-else (c-) |
| 966 | A variety of @code{c-up-conditional} that also stops at @samp{#else} |
| 967 | lines. Normally those lines are ignored. |
| 968 | |
| 969 | @item @kbd{M-x c-down-conditional} |
| 970 | @findex c-down-conditional |
| 971 | @findex down-conditional (c-) |
| 972 | Move forward into the next nested preprocessor conditional, leaving |
| 973 | the mark behind. A prefix argument acts as a repeat count. With a |
| 974 | negative argument, move backward into the previous nested preprocessor |
| 975 | conditional. |
| 976 | |
| 977 | @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the |
| 978 | function stops at them when going forward, but not when going backward. |
| 979 | |
| 980 | @item @kbd{M-x c-down-conditional-with-else} |
| 981 | @findex c-down-conditional-with-else |
| 982 | @findex down-conditional-with-else (c-) |
| 983 | A variety of @code{c-down-conditional} that also stops at @samp{#else} |
| 984 | lines. Normally those lines are ignored. |
| 985 | |
| 986 | @item @kbd{C-c C-p} (@code{c-backward-conditional}) |
| 987 | @itemx @kbd{C-c C-n} (@code{c-forward-conditional}) |
| 988 | @kindex C-c C-p |
| 989 | @kindex C-c C-n |
| 990 | @findex c-backward-conditional |
| 991 | @findex c-forward-conditional |
| 992 | @findex backward-conditional (c-) |
| 993 | @findex forward-conditional (c-) |
| 994 | Move backward or forward across a preprocessor conditional, leaving |
| 995 | the mark behind. A prefix argument acts as a repeat count. With a |
| 996 | negative argument, move in the opposite direction. |
| 997 | |
| 998 | These key sequences are not bound in AWK Mode, which doesn't have |
| 999 | preprocessor statements. |
| 1000 | |
| 1001 | @item @kbd{M-x c-backward-into-nomenclature} |
| 1002 | @itemx @kbd{M-x c-forward-into-nomenclature} |
| 1003 | @findex c-backward-into-nomenclature |
| 1004 | @findex c-forward-into-nomenclature |
| 1005 | @findex backward-into-nomenclature (c-) |
| 1006 | @findex forward-into-nomenclature (c-) |
| 1007 | A popular programming style, especially for object-oriented languages |
| 1008 | such as C++ is to write symbols in a mixed case format, where the |
| 1009 | first letter of each word is capitalized, and not separated by |
| 1010 | underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. |
| 1011 | |
| 1012 | These commands move backward or forward to the beginning of the next |
| 1013 | capitalized word. With prefix argument @var{n}, move @var{n} times. |
| 1014 | If @var{n} is negative, move in the opposite direction. |
| 1015 | |
| 1016 | Note that these two commands have been superseded by |
| 1017 | @code{c-subword-mode}, which you should use instead. @xref{Subword |
| 1018 | Movement}. They might be removed from a future release of @ccmode{}. |
| 1019 | @end table |
| 1020 | |
| 1021 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1022 | @node Filling and Breaking, Minor Modes, Movement Commands, Commands |
| 1023 | @comment node-name, next, previous, up |
| 1024 | @section Filling and Line Breaking Commands |
| 1025 | @cindex text filling |
| 1026 | @cindex line breaking |
| 1027 | @cindex comment handling |
| 1028 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1029 | |
| 1030 | Since there's a lot of normal text in comments and string literals, |
| 1031 | @ccmode{} provides features to edit these like in text mode. The goal |
| 1032 | is to do it seamlessly, i.e. you can use auto fill mode, sentence and |
| 1033 | paragraph movement, paragraph filling, adaptive filling etc. wherever |
| 1034 | there's a piece of normal text without having to think much about it. |
| 1035 | @ccmode{} keeps the indentation, fixes suitable comment line prefixes, |
| 1036 | and so on. |
| 1037 | |
| 1038 | You can configure the exact way comments get filled and broken, and |
| 1039 | where Emacs does auto-filling (see @pxref{Custom Filling and |
| 1040 | Breaking}). Typically, the style system (@pxref{Styles}) will have |
| 1041 | set this up for you, so you probably won't have to bother. |
| 1042 | |
| 1043 | @findex auto-fill-mode |
| 1044 | @cindex Auto Fill mode |
| 1045 | @cindex paragraph filling |
| 1046 | Line breaks are by default handled (almost) the same regardless of |
| 1047 | whether they are made by auto fill mode (@pxref{Auto Fill,,, |
| 1048 | @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with |
| 1049 | @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In |
| 1050 | string literals, the new line gets the same indentation as the |
| 1051 | previous nonempty line.@footnote{You can change this default by |
| 1052 | setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} |
| 1053 | and @pxref{Customizing Indentation})}. |
| 1054 | |
| 1055 | @table @asis |
| 1056 | @item @kbd{M-q} (@code{c-fill-paragraph}) |
| 1057 | @kindex M-q |
| 1058 | @findex c-fill-paragraph |
| 1059 | @findex fill-paragraph (c-) |
| 1060 | @cindex Javadoc markup |
| 1061 | @cindex Pike autodoc markup |
| 1062 | This command fills multiline string literals and both block |
| 1063 | and line style comments. In Java buffers, the Javadoc markup words |
| 1064 | are recognized as paragraph starters. The line oriented Pike autodoc |
| 1065 | markup words are recognized in the same way in Pike mode. |
| 1066 | |
| 1067 | The formatting of the starters (@code{/*}) and enders (@code{*/}) of |
| 1068 | block comments are kept as they were before the filling. I.e., if |
| 1069 | either the starter or ender were on a line of its own, then it stays |
| 1070 | on its own line; conversely, if the delimiter has comment text on its |
| 1071 | line, it keeps at least one word of that text with it on the line. |
| 1072 | |
| 1073 | This command is the replacement for @code{fill-paragraph} in @ccmode{} |
| 1074 | buffers. |
| 1075 | |
| 1076 | @item @kbd{M-j} (@code{c-indent-new-comment-line}) |
| 1077 | @kindex M-j |
| 1078 | @findex c-indent-new-comment-line |
| 1079 | @findex indent-new-comment-line (c-) |
| 1080 | This breaks the current line at point and indents the new line. If |
| 1081 | point was in a comment, the new line gets the proper comment line |
| 1082 | prefix. If point was inside a macro, a backslash is inserted before |
| 1083 | the line break. It is the replacement for |
| 1084 | @code{indent-new-comment-line}. |
| 1085 | |
| 1086 | @item @kbd{M-x c-context-line-break} |
| 1087 | @findex c-context-line-break |
| 1088 | @findex context-line-break (c-) |
| 1089 | Insert a line break suitable to the context: If the point is inside a |
| 1090 | comment, the new line gets the suitable indentation and comment line |
| 1091 | prefix like @code{c-indent-new-comment-line}. In normal code it's |
| 1092 | indented like @code{newline-and-indent} would do. In macros it acts |
| 1093 | like @code{newline-and-indent} but additionally inserts and optionally |
| 1094 | aligns the line ending backslash so that the macro remains unbroken. |
| 1095 | @xref{Custom Macros}, for details about the backslash alignment. In a |
| 1096 | string, a backslash is inserted only if the string is within a |
| 1097 | macro@footnote{In GCC, unescaped line breaks within strings are |
| 1098 | valid.}. |
| 1099 | |
| 1100 | This function is not bound to a key by default, but it's intended to be |
| 1101 | used on the @kbd{RET} key. If you like the behavior of |
| 1102 | @code{newline-and-indent} on @kbd{RET}, you should consider switching to |
| 1103 | this function. @xref{Sample .emacs File}. |
| 1104 | |
| 1105 | @item @kbd{M-x c-context-open-line} |
| 1106 | @findex c-context-open-line |
| 1107 | @findex context-open-line (c-) |
| 1108 | This is to @kbd{C-o} (@kbd{M-x open-line}) as |
| 1109 | @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like |
| 1110 | @code{c-context-line-break} but leaves the point before the inserted |
| 1111 | line break. |
| 1112 | @end table |
| 1113 | |
| 1114 | |
| 1115 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1116 | @node Minor Modes, Electric Keys, Filling and Breaking, Commands |
| 1117 | @comment node-name, next, previous, up |
| 1118 | @section Minor Modes |
| 1119 | @cindex Minor Modes |
| 1120 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1121 | |
| 1122 | @ccmode{} contains several minor-mode-like features that you might |
| 1123 | find useful while writing new code or editing old code: |
| 1124 | |
| 1125 | @table @asis |
| 1126 | @item electric mode |
| 1127 | When this is enabled, certain visible characters cause reformatting as |
| 1128 | they are typed. This is normally helpful, but can be a nuisance when |
| 1129 | editing chaotically formatted code. It can also be disconcerting, |
| 1130 | especially for users who are new to @ccmode{}. |
| 1131 | @item auto-newline mode |
| 1132 | This automatically inserts newlines where you'd probably want to type |
| 1133 | them yourself, e.g. after typing @samp{@}}s. Its action is suppressed |
| 1134 | when electric mode is disabled. |
| 1135 | @item hungry-delete mode |
| 1136 | This lets you delete a contiguous block of whitespace with a single |
| 1137 | key - for example, the newline and indentation just inserted by |
| 1138 | auto-newline when you want to back up and write a comment after the |
| 1139 | last statement. |
| 1140 | @item subword mode |
| 1141 | This mode makes basic word movement commands like @kbd{M-f} |
| 1142 | (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the |
| 1143 | parts of sillycapsed symbols as different words. |
| 1144 | E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, |
| 1145 | @samp{Graphics}, and @samp{Context}. |
| 1146 | @item syntactic-indentation mode |
| 1147 | When this is enabled (which it normally is), indentation commands such |
| 1148 | as @kbd{C-j} indent lines of code according to their syntactic |
| 1149 | structure. Otherwise, a line is simply indented to the same level as |
| 1150 | the previous one and @kbd{@key{TAB}} adjusts the indentation in steps |
| 1151 | of `c-basic-offset'. |
| 1152 | @end table |
| 1153 | |
| 1154 | Full details on how these minor modes work are at @ref{Electric Keys}, |
| 1155 | @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, |
| 1156 | and @ref{Indentation Engine Basics}. |
| 1157 | |
| 1158 | You can toggle each of these minor modes on and off, and you can |
| 1159 | configure @ccmode{} so that it starts up with your favourite |
| 1160 | combination of them (@pxref{Sample .emacs File}). By default, when |
| 1161 | you initialize a buffer, electric mode and syntactic-indentation mode |
| 1162 | are enabled but the other two modes are disabled. |
| 1163 | |
| 1164 | @ccmode{} displays the current state of the first four of these minor |
| 1165 | modes on the modeline by appending letters to the major mode's name, |
| 1166 | one letter for each enabled minor mode - @samp{l} for electric mode, |
| 1167 | @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and |
| 1168 | @samp{w} for subword mode. If all these modes were enabled, you'd see |
| 1169 | @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of |
| 1170 | the language in question for the other languages @ccmode{} supports.}. |
| 1171 | |
| 1172 | Here are the commands to toggle these modes: |
| 1173 | |
| 1174 | @table @asis |
| 1175 | @item @kbd{C-c C-l} (@code{c-toggle-electric-state}) |
| 1176 | @kindex C-c C-l |
| 1177 | @findex c-toggle-electric-state |
| 1178 | @findex toggle-electric-state (c-) |
| 1179 | Toggle electric minor mode. When the command turns the mode off, it |
| 1180 | also suppresses auto-newline mode. |
| 1181 | |
| 1182 | @item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) |
| 1183 | @kindex C-c C-a |
| 1184 | @findex c-toggle-auto-newline |
| 1185 | @findex toggle-auto-newline (c-) |
| 1186 | Toggle auto-newline minor mode. When the command turns the mode on, |
| 1187 | it also enables electric minor mode. |
| 1188 | |
| 1189 | @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} |
| 1190 | @findex c-toggle-hungry-state |
| 1191 | @findex toggle-hungry-state (c-) |
| 1192 | Toggle hungry-delete minor mode. |
| 1193 | |
| 1194 | @item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} |
| 1195 | @findex c-toggle-auto-hungry-state |
| 1196 | @findex toggle-auto-hungry-state (c-) |
| 1197 | Toggle both auto-newline and hungry delete minor modes. |
| 1198 | |
| 1199 | @item @kbd{C-c C-w} (@code{M-x c-subword-mode}) |
| 1200 | @kindex C-c C-w |
| 1201 | @findex c-subword-mode |
| 1202 | @findex subword-mode (c-) |
| 1203 | Toggle subword mode. |
| 1204 | |
| 1205 | @item @kbd{M-x c-toggle-syntactic-indentation} |
| 1206 | @findex c-toggle-syntactic-indentation |
| 1207 | @findex toggle-syntactic-indentation (c-) |
| 1208 | Toggle syntactic-indentation mode. |
| 1209 | @end table |
| 1210 | |
| 1211 | Common to all the toggle functions above is that if they are called |
| 1212 | programmatically, they take an optional numerical argument. A |
| 1213 | positive value will turn on the minor mode (or both of them in the |
| 1214 | case of @code{c-toggle-auto-hungry-state}) and a negative value will |
| 1215 | turn it (or them) off. |
| 1216 | |
| 1217 | |
| 1218 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1219 | @node Electric Keys, Auto-newlines, Minor Modes, Commands |
| 1220 | @comment node-name, next, previous, up |
| 1221 | @section Electric Keys and Keywords |
| 1222 | @cindex electric characters |
| 1223 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1224 | |
| 1225 | Most punctuation keys provide @dfn{electric} behavior - as well as |
| 1226 | inserting themselves they perform some other action, such as |
| 1227 | reindenting the line. This reindentation saves you from having to |
| 1228 | reindent a line manually after typing, say, a @samp{@}}. A few |
| 1229 | keywords, such as @code{else}, also trigger electric action. |
| 1230 | |
| 1231 | You can inhibit the electric behavior described here by disabling |
| 1232 | electric minor mode (@pxref{Minor Modes}). |
| 1233 | |
| 1234 | Common to all these keys is that they only behave electrically when |
| 1235 | used in normal code (as contrasted with getting typed in a string |
| 1236 | literal or comment). Those which cause re-indentation do so only when |
| 1237 | @code{c-syntactic-indentation} has a non-@code{nil} value (which it |
| 1238 | does by default). |
| 1239 | |
| 1240 | These keys and keywords are: |
| 1241 | @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more |
| 1242 | @c like a bug in the code than a bug in this document. It'll get |
| 1243 | @c fixed in the code sometime. |
| 1244 | |
| 1245 | @table @kbd |
| 1246 | @item # |
| 1247 | @kindex # |
| 1248 | @findex c-electric-pound |
| 1249 | @findex electric-pound (c-) |
| 1250 | @vindex c-electric-pound-behavior |
| 1251 | @vindex electric-pound-behavior (c-) |
| 1252 | Pound (bound to @code{c-electric-pound}) is electric when typed as the |
| 1253 | first non-whitespace character on a line and not within a macro |
| 1254 | definition. In this case, the variable @code{c-electric-pound-behavior} |
| 1255 | is consulted for the electric behavior. This variable takes a list |
| 1256 | value, although the only element currently defined is @code{alignleft}, |
| 1257 | which tells this command to force the @samp{#} character into column |
| 1258 | zero. This is useful for entering preprocessor macro definitions. |
| 1259 | |
| 1260 | Pound is not electric in AWK buffers, where @samp{#} starts a comment, |
| 1261 | and is bound to @code{self-insert-command} like any typical printable |
| 1262 | character. |
| 1263 | @c ACM, 2004/8/24: Change this (and the code) to do AWK comment |
| 1264 | @c reindentation. |
| 1265 | |
| 1266 | @item * |
| 1267 | @kindex * |
| 1268 | @itemx / |
| 1269 | @kindex / |
| 1270 | @findex c-electric-star |
| 1271 | @findex electric-star (c-) |
| 1272 | @findex c-electric-slash |
| 1273 | @findex electric-slash (c-) |
| 1274 | A star (bound to @code{c-electric-star}) or a slash |
| 1275 | (@code{c-electric-slash}) causes reindentation when you type it as the |
| 1276 | second component of a C style block comment opener (@samp{/*}) or a |
| 1277 | C++ line comment opener (@samp{//}) respectively, but only if the |
| 1278 | comment opener is the first thing on the line (i.e. there's only |
| 1279 | whitespace before it). |
| 1280 | |
| 1281 | Additionally, you can configure @ccmode{} so that typing a slash at |
| 1282 | the start of a line within a block comment will terminate the |
| 1283 | comment. You don't need to have electric minor mode enabled to get |
| 1284 | this behavior. @xref{Clean-ups}. |
| 1285 | |
| 1286 | In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not |
| 1287 | electric. |
| 1288 | |
| 1289 | @item < |
| 1290 | @kindex < |
| 1291 | @itemx > |
| 1292 | @kindex > |
| 1293 | @findex c-electric-lt-gt |
| 1294 | @findex electric-lt-gt (c-) |
| 1295 | A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is |
| 1296 | electric in two circumstances: when it is an angle bracket in a C++ |
| 1297 | @samp{template} declaration (and similar constructs in other |
| 1298 | languages) and when it is the second of two @kbd{<} or @kbd{>} |
| 1299 | characters in a C++ style stream operator. In either case, the line |
| 1300 | is reindented. Angle brackets in C @samp{#include} directives are not |
| 1301 | electric. |
| 1302 | |
| 1303 | @item ( |
| 1304 | @kindex ( |
| 1305 | @itemx ) |
| 1306 | @kindex ) |
| 1307 | @findex c-electric-paren |
| 1308 | @findex electric-paren (c-) |
| 1309 | The normal parenthesis characters @samp{(} and @samp{)} (bound to |
| 1310 | @code{c-electric-paren}) reindent the current line. This is useful |
| 1311 | for getting the closing parenthesis of an argument list aligned |
| 1312 | automatically. |
| 1313 | |
| 1314 | You can also configure @ccmode{} to insert a space automatically |
| 1315 | between a function name and the @samp{(} you've just typed, and to |
| 1316 | remove it automatically after typing @samp{)}, should the argument |
| 1317 | list be empty. You don't need to have electric minor mode enabled to |
| 1318 | get these actions. @xref{Clean-ups}. |
| 1319 | |
| 1320 | @item @{ |
| 1321 | @kindex @{ |
| 1322 | @itemx @} |
| 1323 | @kindex @} |
| 1324 | @findex c-electric-brace |
| 1325 | @findex electric-brace (c-) |
| 1326 | Typing a brace (bound to @code{c-electric-brace}) reindents the |
| 1327 | current line. Also, one or more newlines might be inserted if |
| 1328 | auto-newline minor mode is enabled. @xref{Auto-newlines}. |
| 1329 | Additionally, you can configure @ccmode{} to compact excess whitespace |
| 1330 | inserted by auto-newline mode in certain circumstances. |
| 1331 | @xref{Clean-ups}. |
| 1332 | |
| 1333 | @item : |
| 1334 | @kindex : |
| 1335 | @findex c-electric-colon |
| 1336 | @findex electric-colon (c-) |
| 1337 | Typing a colon (bound to @code{c-electric-colon}) reindents the |
| 1338 | current line. Additionally, one or more newlines might be inserted if |
| 1339 | auto-newline minor mode is enabled. @xref{Auto-newlines}. If you |
| 1340 | type a second colon immediately after such an auto-newline, by default |
| 1341 | the whitespace between the two colons is removed, leaving a C++ scope |
| 1342 | operator. @xref{Clean-ups}. |
| 1343 | |
| 1344 | If you prefer, you can insert @samp{::} in a single operation, |
| 1345 | avoiding all these spurious reindentations, newlines, and clean-ups. |
| 1346 | @xref{Other Commands}. |
| 1347 | |
| 1348 | @item ; |
| 1349 | @kindex ; |
| 1350 | @itemx , |
| 1351 | @kindex , |
| 1352 | @findex c-electric-semi&comma |
| 1353 | @findex electric-semi&comma (c-) |
| 1354 | Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) |
| 1355 | reindents the current line. Also, a newline might be inserted if |
| 1356 | auto-newline minor mode is enabled. @xref{Auto-newlines}. |
| 1357 | Additionally, you can configure @ccmode{} so that when auto-newline |
| 1358 | has inserted whitespace after a @samp{@}}, it will be removed again |
| 1359 | when you type a semicolon or comma just after it. @xref{Clean-ups}. |
| 1360 | |
| 1361 | @end table |
| 1362 | |
| 1363 | @deffn Command c-electric-continued-statement |
| 1364 | @findex electric-continued-statement (c-) |
| 1365 | |
| 1366 | Certain keywords are electric, causing reindentation when they are |
| 1367 | preceded only by whitespace on the line. The keywords are those that |
| 1368 | continue an earlier statement instead of starting a new one: |
| 1369 | @code{else}, @code{while}, @code{catch} (only in C++ and Java) and |
| 1370 | @code{finally} (only in Java). |
| 1371 | |
| 1372 | An example: |
| 1373 | |
| 1374 | @example |
| 1375 | @group |
| 1376 | for (i = 0; i < 17; i++) |
| 1377 | if (a[i]) |
| 1378 | res += a[i]->offset; |
| 1379 | else |
| 1380 | @end group |
| 1381 | @end example |
| 1382 | |
| 1383 | Here, the @code{else} should be indented like the preceding @code{if}, |
| 1384 | since it continues that statement. @ccmode{} will automatically |
| 1385 | reindent it after the @code{else} has been typed in full, since only |
| 1386 | then is it possible to decide whether it's a new statement or a |
| 1387 | continuation of the preceding @code{if}. |
| 1388 | |
| 1389 | @vindex abbrev-mode |
| 1390 | @findex abbrev-mode |
| 1391 | @cindex Abbrev mode |
| 1392 | @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}}) |
| 1393 | to accomplish this. It's therefore turned on by default in all language |
| 1394 | modes except IDL mode, since CORBA IDL doesn't have any statements. |
| 1395 | @end deffn |
| 1396 | |
| 1397 | |
| 1398 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1399 | @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands |
| 1400 | @comment node-name, next, previous, up |
| 1401 | @section Auto-newline Insertion |
| 1402 | @cindex auto-newline |
| 1403 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1404 | |
| 1405 | When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor |
| 1406 | Modes}), @ccmode{} inserts newlines for you automatically (in certain |
| 1407 | syntactic contexts) when you type a left or right brace, a colon, a |
| 1408 | semicolon, or a comma. Sometimes a newline appears before the |
| 1409 | character you type, sometimes after it, sometimes both. |
| 1410 | |
| 1411 | Auto-newline only triggers when the following conditions hold: |
| 1412 | |
| 1413 | @itemize @bullet |
| 1414 | @item |
| 1415 | Auto-newline minor mode is enabled, as evidenced by the indicator |
| 1416 | @samp{a} after the mode name on the modeline (e.g. @samp{C/a} or |
| 1417 | @samp{C/la}). |
| 1418 | |
| 1419 | @item |
| 1420 | The character was typed at the end of a line, or with only whitespace |
| 1421 | after it, and possibly a @samp{\} escaping the newline. |
| 1422 | |
| 1423 | @item |
| 1424 | The character is not on its own line already. (This applies only to |
| 1425 | insertion of a newline @emph{before} the character.) |
| 1426 | |
| 1427 | @item |
| 1428 | @cindex literal |
| 1429 | @cindex syntactic whitespace |
| 1430 | The character was not typed inside of a literal @footnote{A |
| 1431 | @dfn{literal} is defined as any comment, string, or preprocessor macro |
| 1432 | definition. These constructs are also known as @dfn{syntactic |
| 1433 | whitespace} since they are usually ignored when scanning C code.}. |
| 1434 | |
| 1435 | @item |
| 1436 | No numeric argument was supplied to the command (i.e. it was typed as |
| 1437 | normal, with no @kbd{C-u} prefix). |
| 1438 | @end itemize |
| 1439 | |
| 1440 | You can configure the precise circumstances in which newlines get |
| 1441 | inserted (see @pxref{Custom Auto-newlines}). Typically, the style |
| 1442 | system (@pxref{Styles}) will have set this up for you, so you probably |
| 1443 | won't have to bother. |
| 1444 | |
| 1445 | Sometimes @ccmode{} inserts an auto-newline where you don't want one, |
| 1446 | such as after a @samp{@}} when you're about to type a @samp{;}. |
| 1447 | Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can |
| 1448 | activate an appropriate @dfn{clean-up}, which will remove the excess |
| 1449 | whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a |
| 1450 | full description. See also @ref{Electric Keys} for a summary of |
| 1451 | clean-ups listed by key. |
| 1452 | |
| 1453 | |
| 1454 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1455 | @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands |
| 1456 | @comment node-name, next, previous, up |
| 1457 | @section Hungry Deletion of Whitespace |
| 1458 | @cindex hungry-deletion |
| 1459 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1460 | |
| 1461 | If you want to delete an entire block of whitespace at point, you can |
| 1462 | use @dfn{hungry deletion}. This deletes all the contiguous whitespace |
| 1463 | either before point or after point in a single operation. |
| 1464 | ``Whitespace'' here includes tabs and newlines, but not comments or |
| 1465 | preprocessor commands. Hungry deletion can markedly cut down on the |
| 1466 | number of times you have to hit deletion keys when, for example, |
| 1467 | you've made a mistake on the preceding line and have already pressed |
| 1468 | @kbd{C-j}. |
| 1469 | |
| 1470 | Hungry deletion is a simple feature that some people find extremely |
| 1471 | useful. In fact, you might find yourself wanting it in @strong{all} |
| 1472 | your editing modes! |
| 1473 | |
| 1474 | Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the |
| 1475 | backspace key'' and @dfn{@key{DELETE}} means ``the forward delete |
| 1476 | key''. This is discussed in more detail below. |
| 1477 | |
| 1478 | There are two different ways you can use hungry deletion: |
| 1479 | |
| 1480 | @table @asis |
| 1481 | @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} |
| 1482 | Here you toggle Hungry Delete minor mode with @kbd{M-x |
| 1483 | c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command |
| 1484 | was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding |
| 1485 | for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This |
| 1486 | makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry |
| 1487 | deletion. |
| 1488 | |
| 1489 | @table @asis |
| 1490 | @item @kbd{@key{DEL}} (@code{c-electric-backspace}) |
| 1491 | @kindex DEL |
| 1492 | @findex c-electric-backspace |
| 1493 | @findex electric-backspace (c-) |
| 1494 | This command is run by default when you hit the @kbd{DEL} key. When |
| 1495 | hungry delete mode is enabled, it deletes any amount of whitespace in |
| 1496 | the backwards direction. Otherwise, or when used with a prefix |
| 1497 | argument or in a literal (@pxref{Auto-newlines}), the command just |
| 1498 | deletes backwards in the usual way. (More precisely, it calls the |
| 1499 | function contained in the variable @code{c-backspace-function}, |
| 1500 | passing it the prefix argument, if any.) |
| 1501 | |
| 1502 | @item @code{c-backspace-function} |
| 1503 | @vindex c-backspace-function |
| 1504 | @vindex backspace-function (c-) |
| 1505 | @findex backward-delete-char-untabify |
| 1506 | Hook that gets called by @code{c-electric-backspace} when it doesn't |
| 1507 | do an ``electric'' deletion of the preceding whitespace. The default |
| 1508 | value is @code{backward-delete-char-untabify} |
| 1509 | (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which |
| 1510 | deletes a single character. |
| 1511 | |
| 1512 | @item @kbd{C-d} (@code{c-electric-delete-forward}) |
| 1513 | @kindex C-d |
| 1514 | @findex c-electric-delete-forward |
| 1515 | @findex electric-delete-forward (c-) |
| 1516 | This function, which is bound to @kbd{C-d} by default, works just like |
| 1517 | @code{c-electric-backspace} but in the forward direction. When it |
| 1518 | doesn't do an ``electric'' deletion of the following whitespace, it |
| 1519 | just does @code{delete-char}, more or less. (Strictly speaking, it |
| 1520 | calls the function in @code{c-delete-function} with the prefix |
| 1521 | argument.) |
| 1522 | |
| 1523 | @item @code{c-delete-function} |
| 1524 | @vindex c-delete-function |
| 1525 | @vindex delete-function (c-) |
| 1526 | @findex delete-char |
| 1527 | Hook that gets called by @code{c-electric-delete-forward} when it |
| 1528 | doesn't do an ``electric'' deletion of the following whitespace. The |
| 1529 | default value is @code{delete-char}. |
| 1530 | @end table |
| 1531 | |
| 1532 | @item Using Distinct Bindings |
| 1533 | The other (newer and recommended) way to use hungry deletion is to |
| 1534 | perform @code{c-hungry-delete-backwards} and |
| 1535 | @code{c-hungry-delete-forward} directly through their key sequences |
| 1536 | rather than using the minor mode toggling. |
| 1537 | |
| 1538 | @table @asis |
| 1539 | @item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} |
| 1540 | @kindex C-c C-<backspace> |
| 1541 | @kindex C-c <backspace> |
| 1542 | @kindex C-c C-DEL |
| 1543 | @kindex C-c DEL |
| 1544 | @findex c-hungry-delete-backwards |
| 1545 | @findex hungry-delete-backwards (c-) |
| 1546 | Delete any amount of whitespace in the backwards direction (regardless |
| 1547 | whether hungry-delete mode is enabled or not). This command is bound |
| 1548 | to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more |
| 1549 | natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at |
| 1550 | a character terminal. |
| 1551 | |
| 1552 | @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) |
| 1553 | @kindex C-c C-d |
| 1554 | @kindex C-c C-<DELETE> |
| 1555 | @kindex C-c <DELETE> |
| 1556 | @findex c-hungry-delete-forward |
| 1557 | @findex hungry-delete-forward (c-) |
| 1558 | Delete any amount of whitespace in the forward direction (regardless |
| 1559 | whether hungry-delete mode is enabled or not). This command is bound |
| 1560 | to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the |
| 1561 | same reason as for @key{DEL} above. |
| 1562 | @end table |
| 1563 | @end table |
| 1564 | |
| 1565 | @kindex <delete> |
| 1566 | @kindex <backspace> |
| 1567 | |
| 1568 | When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we |
| 1569 | actually do so without connecting them to the physical keys commonly |
| 1570 | known as @key{Backspace} and @key{Delete}. The default bindings to |
| 1571 | those two keys depends on the flavor of (X)Emacs you are using. |
| 1572 | |
| 1573 | @findex c-electric-delete |
| 1574 | @findex electric-delete (c-) |
| 1575 | @findex c-hungry-delete |
| 1576 | @findex hungry-delete (c-) |
| 1577 | @vindex delete-key-deletes-forward |
| 1578 | In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to |
| 1579 | @code{c-electric-backspace} and the @key{Delete} key is bound to |
| 1580 | @code{c-electric-delete}. You control the direction it deletes in by |
| 1581 | setting the variable @code{delete-key-deletes-forward}, a standard |
| 1582 | XEmacs variable. |
| 1583 | @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). |
| 1584 | When this variable is non-@code{nil}, @code{c-electric-delete} will do |
| 1585 | forward deletion with @code{c-electric-delete-forward}, otherwise it |
| 1586 | does backward deletion with @code{c-electric-backspace}. Similarly, |
| 1587 | @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to |
| 1588 | @code{c-hungry-delete} which is controlled in the same way by |
| 1589 | @code{delete-key-deletes-forward}. |
| 1590 | |
| 1591 | @findex normal-erase-is-backspace-mode |
| 1592 | |
| 1593 | Emacs 21 and later automatically binds @key{Backspace} and |
| 1594 | @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, |
| 1595 | and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} |
| 1596 | etc. If you need to change the bindings through |
| 1597 | @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt |
| 1598 | its extended bindings accordingly. |
| 1599 | |
| 1600 | In earlier (X)Emacs versions, @ccmode{} doesn't bind either |
| 1601 | @key{Backspace} or @key{Delete} directly. Only the key codes |
| 1602 | @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings |
| 1603 | to map the physical keys to them. You might need to modify this |
| 1604 | yourself if the defaults are unsuitable. |
| 1605 | |
| 1606 | Getting your @key{Backspace} and @key{Delete} keys properly set up can |
| 1607 | sometimes be tricky. The information in @ref{DEL Does Not |
| 1608 | Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having |
| 1609 | trouble with this in GNU Emacs. |
| 1610 | |
| 1611 | |
| 1612 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1613 | @node Subword Movement, Other Commands, Hungry WS Deletion, Commands |
| 1614 | @comment node-name, next, previous, up |
| 1615 | @section Subword Movement and Editing |
| 1616 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1617 | |
| 1618 | @cindex nomenclature |
| 1619 | @cindex subword |
| 1620 | In spite of the GNU Coding Standards, it is popular to name a symbol |
| 1621 | by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, |
| 1622 | @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call |
| 1623 | these mixed case symbols @dfn{nomenclatures}. Also, each capitalized |
| 1624 | (or completely uppercase) part of a nomenclature is called a |
| 1625 | @dfn{subword}. Here are some examples: |
| 1626 | |
| 1627 | @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} |
| 1628 | @c This could be converted to @headitem when we require Texinfo 4.7 |
| 1629 | @iftex |
| 1630 | @item @b{Nomenclature} |
| 1631 | @tab @b{Subwords} |
| 1632 | @end iftex |
| 1633 | @ifnottex |
| 1634 | @item Nomenclature |
| 1635 | @tab Subwords |
| 1636 | @item --------------------------------------------------------- |
| 1637 | @end ifnottex |
| 1638 | @item @samp{GtkWindow} |
| 1639 | @tab @samp{Gtk} and @samp{Window} |
| 1640 | @item @samp{EmacsFrameClass} |
| 1641 | @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} |
| 1642 | @item @samp{NSGraphicsContext} |
| 1643 | @tab @samp{NS}, @samp{Graphics}, and @samp{Context} |
| 1644 | @end multitable |
| 1645 | |
| 1646 | The subword minor mode replaces the basic word oriented movement and |
| 1647 | editing commands with variants that recognize subwords in a |
| 1648 | nomenclature and treat them as separate words: |
| 1649 | |
| 1650 | @findex c-forward-subword |
| 1651 | @findex forward-subword (c-) |
| 1652 | @findex c-backward-subword |
| 1653 | @findex backward-subword (c-) |
| 1654 | @findex c-mark-subword |
| 1655 | @findex mark-subword (c-) |
| 1656 | @findex c-kill-subword |
| 1657 | @findex kill-subword (c-) |
| 1658 | @findex c-backward-kill-subword |
| 1659 | @findex backward-kill-subword (c-) |
| 1660 | @findex c-transpose-subwords |
| 1661 | @findex transpose-subwords (c-) |
| 1662 | @findex c-capitalize-subword |
| 1663 | @findex capitalize-subword (c-) |
| 1664 | @findex c-upcase-subword |
| 1665 | @findex upcase-subword (c-) |
| 1666 | @findex c-downcase-subword |
| 1667 | @findex downcase-subword (c-) |
| 1668 | @multitable @columnfractions .20 .40 .40 |
| 1669 | @c This could be converted to @headitem when we require Texinfo 4.7 |
| 1670 | @iftex |
| 1671 | @item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} |
| 1672 | @end iftex |
| 1673 | @ifnottex |
| 1674 | @item Key @tab Word oriented command @tab Subword oriented command |
| 1675 | @item ---------------------------------------------------------------------------- |
| 1676 | @end ifnottex |
| 1677 | @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} |
| 1678 | @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} |
| 1679 | @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} |
| 1680 | @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} |
| 1681 | @item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} |
| 1682 | @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} |
| 1683 | @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} |
| 1684 | @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} |
| 1685 | @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} |
| 1686 | @end multitable |
| 1687 | |
| 1688 | Note that if you have changed the key bindings for the word oriented |
| 1689 | commands in your @file{.emacs} or a similar place, the keys you have |
| 1690 | configured are also used for the corresponding subword oriented |
| 1691 | commands. |
| 1692 | |
| 1693 | Type @kbd{C-c C-w} to toggle subword mode on and off. To make the |
| 1694 | mode turn on automatically, put the following code in your |
| 1695 | @file{.emacs}: |
| 1696 | |
| 1697 | @example |
| 1698 | (add-hook 'c-mode-common-hook |
| 1699 | (lambda () (c-subword-mode 1))) |
| 1700 | @end example |
| 1701 | |
| 1702 | As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} |
| 1703 | buffers by typing @kbd{M-x c-subword-mode}. |
| 1704 | |
| 1705 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1706 | @node Other Commands, , Subword Movement, Commands |
| 1707 | @comment node-name, next, previous, up |
| 1708 | @section Other Commands |
| 1709 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1710 | |
| 1711 | Here are the various other commands that didn't fit anywhere else: |
| 1712 | |
| 1713 | @table @asis |
| 1714 | @item @kbd{C-c .} (@code{c-set-style}) |
| 1715 | @kindex C-c . |
| 1716 | @findex c-set-style |
| 1717 | @findex set-style (c-) |
| 1718 | Switch to the specified style in the current buffer. Use like this: |
| 1719 | |
| 1720 | @example |
| 1721 | @kbd{C-c . @var{style-name} @key{RET}} |
| 1722 | @end example |
| 1723 | |
| 1724 | You can use the @key{TAB} in the normal way to do completion on the |
| 1725 | style name. Note that all style names are case insensitive, even the |
| 1726 | ones you define yourself. |
| 1727 | |
| 1728 | Setting a style in this way does @emph{not} automatically reindent your |
| 1729 | file. For commands that you can use to view the effect of your changes, |
| 1730 | see @ref{Indentation Commands} and @ref{Filling and Breaking}. |
| 1731 | |
| 1732 | For details of the @ccmode{} style system, see @ref{Styles}. |
| 1733 | @item @kbd{C-c :} (@code{c-scope-operator}) |
| 1734 | @kindex C-c : |
| 1735 | @findex c-scope-operator |
| 1736 | @findex scope-operator (c-) |
| 1737 | In C++, it is also sometimes desirable to insert the double-colon scope |
| 1738 | operator without performing the electric behavior of colon insertion. |
| 1739 | @kbd{C-c :} does just this. |
| 1740 | |
| 1741 | @item @kbd{C-c C-\} (@code{c-backslash-region}) |
| 1742 | @kindex C-c C-\ |
| 1743 | @findex c-backslash-region |
| 1744 | @findex backslash-region (c-) |
| 1745 | This function inserts and aligns or deletes end-of-line backslashes in |
| 1746 | the current region. These are typically used in multi-line macros. |
| 1747 | |
| 1748 | With no prefix argument, it inserts any missing backslashes and aligns |
| 1749 | them according to the @code{c-backslash-column} and |
| 1750 | @code{c-backslash-max-column} variables. With a prefix argument, it |
| 1751 | deletes any backslashes. |
| 1752 | |
| 1753 | The function does not modify blank lines at the start of the region. If |
| 1754 | the region ends at the start of a line, it always deletes the backslash |
| 1755 | (if any) at the end of the previous line. |
| 1756 | |
| 1757 | To customize the precise workings of this command, @ref{Custom Macros}. |
| 1758 | @end table |
| 1759 | |
| 1760 | @noindent |
| 1761 | The recommended line breaking function, @code{c-context-line-break} |
| 1762 | (@pxref{Filling and Breaking}), is especially nice if you edit |
| 1763 | multiline macros frequently. When used inside a macro, it |
| 1764 | automatically inserts and adjusts the mandatory backslash at the end |
| 1765 | of the line to keep the macro together, and it leaves the point at the |
| 1766 | right indentation column for the code. Thus you can write code inside |
| 1767 | macros almost exactly as you can elsewhere, without having to bother |
| 1768 | with the trailing backslashes. |
| 1769 | |
| 1770 | @table @asis |
| 1771 | @item @kbd{C-c C-e} (@code{c-macro-expand}) |
| 1772 | @kindex C-c C-e |
| 1773 | @findex c-macro-expand |
| 1774 | @findex macro-expand (c-) |
| 1775 | This command expands C, C++, Objective C or Pike macros in the region, |
| 1776 | using an appropriate external preprocessor program. Normally it |
| 1777 | displays its output in a temporary buffer, but if you give it a prefix |
| 1778 | arg (with @kbd{C-u C-c C-e}) it will overwrite the original region |
| 1779 | with the expansion. |
| 1780 | |
| 1781 | The command does not work in any of the other modes, and the key |
| 1782 | sequence is not bound in these other modes. |
| 1783 | |
| 1784 | @code{c-macro-expand} isn't actually part of @ccmode{}, even though it |
| 1785 | is bound to a @ccmode{} key sequence. If you need help setting it up |
| 1786 | or have other problems with it, you can either read its source code or |
| 1787 | ask for help in the standard (X)Emacs forums. |
| 1788 | @end table |
| 1789 | |
| 1790 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1791 | @node Font Locking, Config Basics, Commands, Top |
| 1792 | @comment node-name, next, previous, up |
| 1793 | @chapter Font Locking |
| 1794 | @cindex font locking |
| 1795 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1796 | |
| 1797 | @cindex Font Lock mode |
| 1798 | |
| 1799 | @ccmode{} provides font locking for its supported languages by |
| 1800 | supplying patterns for use with Font Lock mode. This means that you |
| 1801 | get distinct faces on the various syntactic parts such as comments, |
| 1802 | strings, keywords and types, which is very helpful in telling them |
| 1803 | apart at a glance and discovering syntactic errors. @xref{Font |
| 1804 | Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in |
| 1805 | @ccmode{} buffers. |
| 1806 | |
| 1807 | @strong{Please note:} The font locking in AWK mode is currently not |
| 1808 | integrated with the rest of @ccmode{}. Only the last section of this |
| 1809 | chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other |
| 1810 | sections apply to the other languages. |
| 1811 | |
| 1812 | @menu |
| 1813 | * Font Locking Preliminaries:: |
| 1814 | * Faces:: |
| 1815 | * Doc Comments:: |
| 1816 | * AWK Mode Font Locking:: |
| 1817 | @end menu |
| 1818 | |
| 1819 | |
| 1820 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1821 | @node Font Locking Preliminaries, Faces, Font Locking, Font Locking |
| 1822 | @comment node-name, next, previous, up |
| 1823 | @section Font Locking Preliminaries |
| 1824 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1825 | |
| 1826 | The font locking for most of the @ccmode{} languages were provided |
| 1827 | directly by the Font Lock package prior to version 5.30 of @ccmode{}. |
| 1828 | In the transition to @ccmode{} the patterns have been reworked |
| 1829 | completely and are applied uniformly across all the languages except AWK |
| 1830 | mode, just like the indentation rules (although each language still has |
| 1831 | some peculiarities of its own, of course). Since the languages |
| 1832 | previously had completely separate font locking patterns, this means |
| 1833 | that it's a bit different in most languages now. |
| 1834 | |
| 1835 | The main goal for the font locking in @ccmode{} is accuracy, to provide |
| 1836 | a dependable aid in recognizing the various constructs. Some, like |
| 1837 | strings and comments, are easy to recognize while others, like |
| 1838 | declarations and types, can be very tricky. @ccmode{} can go to great |
| 1839 | lengths to recognize declarations and casts correctly, especially when |
| 1840 | the types aren't recognized by standard patterns. This is a fairly |
| 1841 | demanding analysis which can be slow on older hardware, and it can |
| 1842 | therefore be disabled by choosing a lower decoration level with the |
| 1843 | variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, |
| 1844 | emacs, GNU Emacs Manual}). |
| 1845 | |
| 1846 | @vindex font-lock-maximum-decoration |
| 1847 | |
| 1848 | The decoration levels are used as follows: |
| 1849 | |
| 1850 | @enumerate |
| 1851 | @comment 1 |
| 1852 | @item |
| 1853 | Minimal font locking: Fontify only comments, strings and preprocessor |
| 1854 | directives (in the languages that use cpp). |
| 1855 | |
| 1856 | @comment 2 |
| 1857 | @item |
| 1858 | Fast font locking: In addition to level 1, fontify keywords, simple |
| 1859 | types and declarations that are easy to recognize. The variables |
| 1860 | @code{*-font-lock-extra-types} (where @samp{*} is the name of the |
| 1861 | language) are used to recognize types (see below). Documentation |
| 1862 | comments like Javadoc are fontified according to |
| 1863 | @code{c-doc-comment-style} (@pxref{Doc Comments}). |
| 1864 | |
| 1865 | Use this if you think the font locking is too slow. It's the closest |
| 1866 | corresponding level to level 3 in the old font lock patterns. |
| 1867 | |
| 1868 | @comment 3 |
| 1869 | @item |
| 1870 | Accurate font locking: Like level 2 but uses a different approach that |
| 1871 | can recognize types and declarations much more accurately. The |
| 1872 | @code{*-font-lock-extra-types} variables are still used, but user |
| 1873 | defined types are recognized correctly anyway in most cases. Therefore |
| 1874 | those variables should be fairly restrictive and not contain patterns |
| 1875 | that are uncertain. |
| 1876 | |
| 1877 | @cindex Lazy Lock mode |
| 1878 | @cindex Just-in-time Lock mode |
| 1879 | |
| 1880 | This level is designed for fairly modern hardware and a font lock |
| 1881 | support mode like Lazy Lock or Just-in-time Lock mode that only |
| 1882 | fontifies the parts that are actually shown. Fontifying the whole |
| 1883 | buffer at once can easily get bothersomely slow even on contemporary |
| 1884 | hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. |
| 1885 | @end enumerate |
| 1886 | |
| 1887 | @cindex user defined types |
| 1888 | @cindex types, user defined |
| 1889 | |
| 1890 | Since user defined types are hard to recognize you can provide |
| 1891 | additional regexps to match those you use: |
| 1892 | |
| 1893 | @defopt c-font-lock-extra-types |
| 1894 | @defoptx c++-font-lock-extra-types |
| 1895 | @defoptx objc-font-lock-extra-types |
| 1896 | @defoptx java-font-lock-extra-types |
| 1897 | @defoptx idl-font-lock-extra-types |
| 1898 | @defoptx pike-font-lock-extra-types |
| 1899 | For each language there's a variable @code{*-font-lock-extra-types}, |
| 1900 | where @samp{*} stands for the language in question. It contains a list |
| 1901 | of regexps that matches identifiers that should be recognized as types, |
| 1902 | e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} |
| 1903 | as is customary in C code. Each regexp should not match more than a |
| 1904 | single identifier. |
| 1905 | |
| 1906 | The default values contain regexps for many types in standard runtime |
| 1907 | libraries that are otherwise difficult to recognize, and patterns for |
| 1908 | standard type naming conventions like the @samp{_t} suffix in C and C++. |
| 1909 | Java, Objective-C and Pike have as a convention to start class names |
| 1910 | with capitals, so there are patterns for that in those languages. |
| 1911 | |
| 1912 | Despite the names of these variables, they are not only used for |
| 1913 | fontification but in other places as well where @ccmode{} needs to |
| 1914 | recognize types. |
| 1915 | @end defopt |
| 1916 | |
| 1917 | |
| 1918 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1919 | @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking |
| 1920 | @comment node-name, next, previous, up |
| 1921 | @section Faces |
| 1922 | @cindex faces |
| 1923 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 1924 | |
| 1925 | @ccmode{} attempts to use the standard faces for programming languages |
| 1926 | in accordance with their intended purposes as far as possible. No extra |
| 1927 | faces are currently provided, with the exception of a replacement face |
| 1928 | @code{c-invalid-face} for emacsen that don't provide |
| 1929 | @code{font-lock-warning-face}. |
| 1930 | |
| 1931 | @itemize @bullet |
| 1932 | @item |
| 1933 | @vindex font-lock-comment-face |
| 1934 | Normal comments are fontified in @code{font-lock-comment-face}. |
| 1935 | |
| 1936 | @item |
| 1937 | @vindex font-lock-doc-face |
| 1938 | @vindex font-lock-doc-string-face |
| 1939 | @vindex font-lock-comment-face |
| 1940 | Comments that are recognized as documentation (@pxref{Doc Comments}) |
| 1941 | get @code{font-lock-doc-face} (Emacs) or |
| 1942 | @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If |
| 1943 | they don't then @code{font-lock-comment-face} is used. |
| 1944 | |
| 1945 | @item |
| 1946 | @vindex font-lock-string-face |
| 1947 | String and character literals are fontified in |
| 1948 | @code{font-lock-string-face}. |
| 1949 | |
| 1950 | @item |
| 1951 | @vindex font-lock-keyword-face |
| 1952 | Keywords are fontified with @code{font-lock-keyword-face}. |
| 1953 | |
| 1954 | @item |
| 1955 | @vindex font-lock-function-name-face |
| 1956 | @code{font-lock-function-name-face} is used for function names in |
| 1957 | declarations and definitions, and classes in those contexts. It's also |
| 1958 | used for preprocessor defines with arguments. |
| 1959 | |
| 1960 | @item |
| 1961 | @vindex font-lock-variable-name-face |
| 1962 | Variables in declarations and definitions, and other identifiers in such |
| 1963 | variable contexts, get @code{font-lock-variable-name-face}. It's also |
| 1964 | used for preprocessor defines without arguments. |
| 1965 | |
| 1966 | @item |
| 1967 | @vindex font-lock-constant-face |
| 1968 | @vindex font-lock-reference-face |
| 1969 | Builtin constants are fontified in @code{font-lock-constant-face} if it |
| 1970 | exists, @code{font-lock-reference-face} otherwise. As opposed to the |
| 1971 | preceding two faces, this is used on the names in expressions, and it's |
| 1972 | not used in declarations, even if there happen to be a @samp{const} in |
| 1973 | them somewhere. |
| 1974 | |
| 1975 | @item |
| 1976 | @vindex font-lock-type-face |
| 1977 | @code{font-lock-type-face} is put on types (both predefined and user |
| 1978 | defined) and classes in type contexts. |
| 1979 | |
| 1980 | @item |
| 1981 | @vindex font-lock-constant-face |
| 1982 | @vindex font-lock-reference-face |
| 1983 | Label identifiers get @code{font-lock-constant-face} if it exists, |
| 1984 | @code{font-lock-reference-face} otherwise. |
| 1985 | |
| 1986 | @item |
| 1987 | Name qualifiers and identifiers for scope constructs are fontified like |
| 1988 | labels. |
| 1989 | |
| 1990 | @item |
| 1991 | Special markup inside documentation comments are also fontified like |
| 1992 | labels. |
| 1993 | |
| 1994 | @item |
| 1995 | @vindex font-lock-preprocessor-face |
| 1996 | @vindex font-lock-builtin-face |
| 1997 | @vindex font-lock-reference-face |
| 1998 | Preprocessor directives get @code{font-lock-preprocessor-face} if it |
| 1999 | exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} |
| 2000 | or @code{font-lock-reference-face}, for lack of a closer equivalent. |
| 2001 | |
| 2002 | @item |
| 2003 | @vindex font-lock-warning-face |
| 2004 | @vindex c-invalid-face |
| 2005 | @vindex invalid-face (c-) |
| 2006 | Some kinds of syntactic errors are fontified with |
| 2007 | @code{font-lock-warning-face} in Emacs. In older XEmacs versions |
| 2008 | there's no corresponding standard face, so there a special |
| 2009 | @code{c-invalid-face} is used, which is defined to stand out sharply by |
| 2010 | default. |
| 2011 | |
| 2012 | Note that it's not used for @samp{#error} or @samp{#warning} directives, |
| 2013 | since those aren't syntactic errors in themselves. |
| 2014 | @end itemize |
| 2015 | |
| 2016 | |
| 2017 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2018 | @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking |
| 2019 | @comment node-name, next, previous, up |
| 2020 | @section Documentation Comments |
| 2021 | @cindex documentation comments |
| 2022 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2023 | |
| 2024 | There are various tools to supply documentation in the source as |
| 2025 | specially structured comments, e.g. the standard Javadoc tool in Java. |
| 2026 | @ccmode{} provides an extensible mechanism to fontify such comments and |
| 2027 | the special markup inside them. |
| 2028 | |
| 2029 | @defopt c-doc-comment-style |
| 2030 | @vindex doc-comment-style (c-) |
| 2031 | This is a style variable that specifies which documentation comment |
| 2032 | style to recognize, e.g. @code{javadoc} for Javadoc comments. |
| 2033 | |
| 2034 | The value may also be a list of styles, in which case all of them are |
| 2035 | recognized simultaneously (presumably with markup cues that don't |
| 2036 | conflict). |
| 2037 | |
| 2038 | The value may also be an association list to specify different comment |
| 2039 | styles for different languages. The symbol for the major mode is then |
| 2040 | looked up in the alist, and the value of that element is interpreted as |
| 2041 | above if found. If it isn't found then the symbol `other' is looked up |
| 2042 | and its value is used instead. |
| 2043 | |
| 2044 | The default value for @code{c-doc-comment-style} is |
| 2045 | @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. |
| 2046 | |
| 2047 | Note that @ccmode{} uses this variable to set other variables that |
| 2048 | handle fontification etc. That's done at mode initialization or when |
| 2049 | you switch to a style which sets this variable. Thus, if you change it |
| 2050 | in some other way, e.g. interactively in a CC Mode buffer, you will need |
| 2051 | to do @kbd{M-x java-mode} (or whatever mode you're currently using) to |
| 2052 | reinitialize. |
| 2053 | |
| 2054 | @findex c-setup-doc-comment-style |
| 2055 | @findex setup-doc-comment-style (c-) |
| 2056 | Note also that when @ccmode{} starts up, the other variables are |
| 2057 | modified before the mode hooks are run. If you change this variable in |
| 2058 | a mode hook, you'll have to call @code{c-setup-doc-comment-style} |
| 2059 | afterwards to redo that work. |
| 2060 | @end defopt |
| 2061 | |
| 2062 | @ccmode{} currently provides handing of the following doc comment |
| 2063 | styles: |
| 2064 | |
| 2065 | @table @code |
| 2066 | @item javadoc |
| 2067 | @cindex Javadoc markup |
| 2068 | Javadoc comments, the standard tool in Java. |
| 2069 | |
| 2070 | @item autodoc |
| 2071 | @cindex Pike autodoc markup |
| 2072 | For Pike autodoc markup, the standard in Pike. |
| 2073 | |
| 2074 | @item gtkdoc |
| 2075 | @cindex GtkDoc markup |
| 2076 | For GtkDoc markup, widely used in the Gnome community. |
| 2077 | @end table |
| 2078 | |
| 2079 | The above is by no means complete. If you'd like to see support for |
| 2080 | other doc comment styles, please let us know (@pxref{Mailing Lists and |
| 2081 | Bug Reports}). |
| 2082 | |
| 2083 | You can also write your own doc comment fontification support to use |
| 2084 | with @code{c-doc-comment-style}: Supply a variable or function |
| 2085 | @code{*-font-lock-keywords} where @samp{*} is the name you want to use |
| 2086 | in @code{c-doc-comment-style}. If it's a variable, it's prepended to |
| 2087 | @code{font-lock-keywords}. If it's a function, it's called at mode |
| 2088 | initialization and the result is prepended. For an example, see |
| 2089 | @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. |
| 2090 | |
| 2091 | If you add support for another doc comment style, please consider |
| 2092 | contributing it - send a note to @email{bug-cc-mode@@gnu.org}. |
| 2093 | |
| 2094 | |
| 2095 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2096 | @node AWK Mode Font Locking, , Doc Comments, Font Locking |
| 2097 | @comment node-name, next, previous, up |
| 2098 | @section AWK Mode Font Locking |
| 2099 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2100 | |
| 2101 | The general appearance of font-locking in AWK mode is much like in any |
| 2102 | other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs |
| 2103 | Lisp Reference Manual}. |
| 2104 | |
| 2105 | The following faces are, however, used in a non-standard fashion in |
| 2106 | AWK mode: |
| 2107 | |
| 2108 | @table @asis |
| 2109 | @item @code{font-lock-variable-name-face} |
| 2110 | This face was intended for variable declarations. Since variables are |
| 2111 | not declared in AWK, this face is used instead for AWK system |
| 2112 | variables (such as @code{NF}) and ``Special File Names'' (such as |
| 2113 | @code{"/dev/stderr"}). |
| 2114 | |
| 2115 | @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) |
| 2116 | This face is normally used for preprocessor directives in @ccmode{}. |
| 2117 | There are no such things in AWK, so this face is used instead for |
| 2118 | standard functions (such as @code{match}). |
| 2119 | |
| 2120 | @item @code{font-lock-string-face} |
| 2121 | As well as being used for strings, including localizable strings, |
| 2122 | (delimited by @samp{"} and @samp{_"}), this face is also used for AWK |
| 2123 | regular expressions (delimited by @samp{/}). |
| 2124 | |
| 2125 | @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) |
| 2126 | This face highlights the following syntactically invalid AWK |
| 2127 | constructs: |
| 2128 | |
| 2129 | @itemize @bullet |
| 2130 | @item |
| 2131 | An unterminated string or regular expression. Here the opening |
| 2132 | delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in |
| 2133 | @code{font-lock-warning-face}. This is most noticeable when typing in a |
| 2134 | new string/regular expression into a buffer, when the warning-face |
| 2135 | serves as a continual reminder to terminate the construct. |
| 2136 | |
| 2137 | AWK mode fontifies unterminated strings/regular expressions |
| 2138 | differently from other modes: Only the text up to the end of the line |
| 2139 | is fontified as a string (escaped newlines being handled correctly), |
| 2140 | rather than the text up to the next string quote. |
| 2141 | |
| 2142 | @item |
| 2143 | A space between the function name and opening parenthesis when calling |
| 2144 | a user function. The last character of the function name and the |
| 2145 | opening parenthesis are highlighted. This font-locking rule will |
| 2146 | spuriously highlight a valid concatenation expression where an |
| 2147 | identifier precedes a parenthesised expression. Unfortunately. |
| 2148 | |
| 2149 | @item |
| 2150 | Whitespace following the @samp{\} in what otherwise looks like an |
| 2151 | escaped newline. The @samp{\} is highlighted. |
| 2152 | @end itemize |
| 2153 | @end table |
| 2154 | |
| 2155 | |
| 2156 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2157 | @node Config Basics, Custom Filling and Breaking, Font Locking, Top |
| 2158 | @comment node-name, next, previous, up |
| 2159 | @chapter Configuration Basics |
| 2160 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2161 | |
| 2162 | @cindex Emacs Initialization File |
| 2163 | @cindex Configuration |
| 2164 | You configure @ccmode{} by setting Lisp variables and calling (and |
| 2165 | perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't |
| 2166 | difficult.}, which is usually done by adding code to an Emacs |
| 2167 | initialization file. This file might be @file{site-start.el} or |
| 2168 | @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some |
| 2169 | other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For |
| 2170 | the sake of conciseness, we just call this file ``your @file{.emacs}'' |
| 2171 | throughout the rest of the manual. |
| 2172 | |
| 2173 | Several of these variables (currently 16), are known collectively as |
| 2174 | @dfn{style variables}. @ccmode{} provides a special mechanism, known |
| 2175 | as @dfn{styles} to make it easier to set these variables as a group, |
| 2176 | to ``inherit'' settings from one style into another, and so on. Style |
| 2177 | variables remain ordinary Lisp variables, whose values can be read and |
| 2178 | changed independently of the style system. @xref{Style Variables}. |
| 2179 | |
| 2180 | There are several ways you can write the code, depending on the |
| 2181 | precise effect you want---they are described further down on this page. |
| 2182 | If you are new to @ccmode{}, we suggest you begin with the simplest |
| 2183 | method, ``Top-level commands or the customization interface''. |
| 2184 | |
| 2185 | If you make conflicting settings in several of these ways, the way |
| 2186 | that takes precedence is the one that appears latest in this list: |
| 2187 | @itemize @asis |
| 2188 | @item |
| 2189 | @table @asis |
| 2190 | @item Style |
| 2191 | @itemx Top-level command or ``customization interface'' |
| 2192 | @itemx Hook |
| 2193 | @itemx File Style |
| 2194 | @end table |
| 2195 | @end itemize |
| 2196 | |
| 2197 | Here is a summary of the different ways of writing your configuration |
| 2198 | settings: |
| 2199 | |
| 2200 | @table @asis |
| 2201 | @item Top-level commands or the ``customization interface'' |
| 2202 | Most simply, you can write @code{setq} and similar commands at the top |
| 2203 | level of your @file{.emacs} file. When you load a @ccmode{} buffer, |
| 2204 | it initializes its configuration from these global values (at least, |
| 2205 | for those settings you have given values to), so it makes sense to |
| 2206 | have these @code{setq} commands run @emph{before} @ccmode{} is first |
| 2207 | initialized---in particular, before any call to @code{desktop-read} |
| 2208 | (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For |
| 2209 | example, you might set c-basic-offset thus: |
| 2210 | |
| 2211 | @example |
| 2212 | (setq c-basic-offset 4) |
| 2213 | @end example |
| 2214 | |
| 2215 | You can use the more user friendly Customization interface instead, |
| 2216 | but this manual does not cover in detail how that works. To do this, |
| 2217 | start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. |
| 2218 | @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. |
| 2219 | @c The following note really belongs in the Emacs manual. |
| 2220 | Emacs normally writes the customizations at the end of your |
| 2221 | @file{.emacs} file. If you use @code{desktop-read}, you should edit |
| 2222 | your @file{.emacs} to place the call to @code{desktop-read} @emph{after} |
| 2223 | the customizations. |
| 2224 | |
| 2225 | The first initialization of @ccmode{} puts a snapshot of the |
| 2226 | configuration settings into the special style @code{user}. |
| 2227 | @xref{Built-in Styles}. |
| 2228 | |
| 2229 | For basic use of Emacs, either of these ways of configuring is |
| 2230 | adequate. However, the settings are then the same in all @ccmode{} |
| 2231 | buffers and it can be clumsy to communicate them between programmers. |
| 2232 | For more flexibility, you'll want to use one (or both) of @ccmode{}'s |
| 2233 | more sophisticated facilities, hooks and styles. |
| 2234 | |
| 2235 | @item Hooks |
| 2236 | An Emacs @dfn{hook} is a place to put Lisp functions that you want |
| 2237 | Emacs to execute later in specific circumstances. |
| 2238 | @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main |
| 2239 | hook and a language-specific hook for each language it supports - any |
| 2240 | functions you put onto these hooks get executed as the last part of a |
| 2241 | buffer's initialization. Typically you put most of your customization |
| 2242 | within the main hook, and use the language-specific hooks to vary the |
| 2243 | customization settings between language modes. For example, if you |
| 2244 | wanted different (non-standard) values of @code{c-basic-offset} in C |
| 2245 | Mode and Java Mode buffers, you could do it like this: |
| 2246 | |
| 2247 | @example |
| 2248 | @group |
| 2249 | (defun my-c-mode-hook () |
| 2250 | (setq c-basic-offset 3)) |
| 2251 | (add-hook 'c-mode-hook 'my-c-mode-hook) |
| 2252 | |
| 2253 | (defun my-java-mode-hook () |
| 2254 | (setq c-basic-offset 6)) |
| 2255 | (add-hook 'java-mode-hook 'my-java-mode-hook) |
| 2256 | @end group |
| 2257 | @end example |
| 2258 | |
| 2259 | See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. |
| 2260 | |
| 2261 | @item Styles |
| 2262 | A @ccmode{} @dfn{style} is a coherent collection of customizations |
| 2263 | with a name. At any time, exactly one style is active in each |
| 2264 | @ccmode{} buffer, either the one you have selected or a default. |
| 2265 | @ccmode{} is delivered with several existing styles. Additionally, |
| 2266 | you can create your own styles, possibly based on these existing |
| 2267 | styles. If you worked in a programming team called the ``Free |
| 2268 | Group'', which had its own coding standards, you might well have this |
| 2269 | in your @file{.emacs} file: |
| 2270 | |
| 2271 | @example |
| 2272 | (setq c-default-style '((java-mode . "java") |
| 2273 | (awk-mode . "awk") |
| 2274 | (other . "free-group-style"))) |
| 2275 | @end example |
| 2276 | |
| 2277 | See @ref{Styles} for fuller details on using @ccmode{} styles and how |
| 2278 | to create them. |
| 2279 | |
| 2280 | @item File Styles |
| 2281 | A @dfn{file style} is a rarely used variant of the ``style'' mechanism |
| 2282 | described above, which applies to an individual source file. To use |
| 2283 | it, you set certain Emacs local variables in a special block at the |
| 2284 | end of the source file. @xref{File Styles}. |
| 2285 | |
| 2286 | @item Hooks with Styles |
| 2287 | For ultimate flexibility, you can use hooks and styles together. For |
| 2288 | example, if your team were developing a product which required a |
| 2289 | Linux driver, you'd probably want to use the ``linux'' style for the |
| 2290 | driver, and your own team's style for the rest of the code. You |
| 2291 | could achieve this with code like this in your @file{.emacs}: |
| 2292 | |
| 2293 | @example |
| 2294 | @group |
| 2295 | (defun my-c-mode-hook () |
| 2296 | (c-set-style |
| 2297 | (if (and (buffer-file-name) |
| 2298 | (string-match "/usr/src/linux" (buffer-file-name))) |
| 2299 | "linux" |
| 2300 | "free-group-style"))) |
| 2301 | (add-hook 'c-mode-hook 'my-c-mode-hook) |
| 2302 | @end group |
| 2303 | @end example |
| 2304 | |
| 2305 | In a programming team, a hook is a also a good place for each member |
| 2306 | to put his own personal preferences. For example, you might be the |
| 2307 | only person in your team who likes Auto-newline minor mode. You could |
| 2308 | have it enabled by default by placing the following in your |
| 2309 | @file{.emacs}: |
| 2310 | |
| 2311 | @example |
| 2312 | @group |
| 2313 | (defun my-turn-on-auto-newline () |
| 2314 | (c-toggle-auto-newline 1)) |
| 2315 | (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) |
| 2316 | @end group |
| 2317 | @end example |
| 2318 | @end table |
| 2319 | |
| 2320 | @menu |
| 2321 | * CC Hooks:: |
| 2322 | * Style Variables:: |
| 2323 | * Styles:: |
| 2324 | @end menu |
| 2325 | |
| 2326 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2327 | @node CC Hooks, Style Variables, Config Basics, Config Basics |
| 2328 | @comment node-name, next, previous, up |
| 2329 | @section Hooks |
| 2330 | @cindex mode hooks |
| 2331 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2332 | @c The node name is "CC Hooks" rather than "Hooks" because of a bug in |
| 2333 | @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. |
| 2334 | @c If you go to "Config Basics" and hit <CR> on the xref to "CC |
| 2335 | @c Hooks" the function Info-follow-reference searches for "*Note: CC |
| 2336 | @c Hooks" from the beginning of the page. If this node were instead |
| 2337 | @c named "Hooks", that search would spuriously find "*Note: |
| 2338 | @c Hooks(elisp)" and go to the wrong node. |
| 2339 | |
| 2340 | @ccmode{} provides several hooks that you can use to customize the |
| 2341 | mode for your coding style. The main hook is |
| 2342 | @code{c-mode-common-hook}; typically, you'll put the bulk of your |
| 2343 | customizations here. In addition, each language mode has its own |
| 2344 | hook, allowing you to fine tune your settings individually for the |
| 2345 | different @ccmode{} languages, and there is a package initialization |
| 2346 | hook. Finally, there is @code{c-special-indent-hook}, which enables |
| 2347 | you to solve anomalous indentation problems. It is described in |
| 2348 | @ref{Other Indentation}, not here. All these hooks adhere to the |
| 2349 | standard Emacs conventions. |
| 2350 | |
| 2351 | When you open a buffer, @ccmode{} first initializes it with the |
| 2352 | currently active style (@pxref{Styles}). Then it calls |
| 2353 | @code{c-mode-common-hook}, and finally it calls the language-specific |
| 2354 | hook. Thus, any style settings done in these hooks will override |
| 2355 | those set by @code{c-default-style}. |
| 2356 | |
| 2357 | @defvar c-initialization-hook |
| 2358 | @vindex initialization-hook (c-) |
| 2359 | Hook run only once per Emacs session, when @ccmode{} is initialized. |
| 2360 | This is a good place to change key bindings (or add new ones) in any |
| 2361 | of the @ccmode{} key maps. @xref{Sample .emacs File}. |
| 2362 | @end defvar |
| 2363 | |
| 2364 | @defvar c-mode-common-hook |
| 2365 | @vindex mode-common-hook (c-) |
| 2366 | Common hook across all languages. It's run immediately before the |
| 2367 | language specific hook. |
| 2368 | @end defvar |
| 2369 | |
| 2370 | @defvar c-mode-hook |
| 2371 | @defvarx c++-mode-hook |
| 2372 | @defvarx objc-mode-hook |
| 2373 | @defvarx java-mode-hook |
| 2374 | @defvarx idl-mode-hook |
| 2375 | @defvarx pike-mode-hook |
| 2376 | @defvarx awk-mode-hook |
| 2377 | The language specific mode hooks. The appropriate one is run as the |
| 2378 | last thing when you enter that language mode. |
| 2379 | @end defvar |
| 2380 | |
| 2381 | Although these hooks are variables defined in @ccmode{}, you can give |
| 2382 | them values before @ccmode{}'s code is loaded---indeed, this is the |
| 2383 | only way to use @code{c-initialization-hook}. Their values aren't |
| 2384 | overwritten when @ccmode{} gets loaded. |
| 2385 | |
| 2386 | Here's a simplified example of what you can add to your @file{.emacs} |
| 2387 | file to do things whenever any @ccmode{} language is edited. See the |
| 2388 | Emacs manuals for more information on customizing Emacs via hooks. |
| 2389 | @xref{Sample .emacs File}, for a more complete sample @file{.emacs} |
| 2390 | file. |
| 2391 | |
| 2392 | @example |
| 2393 | (defun my-c-mode-common-hook () |
| 2394 | ;; my customizations for all of c-mode and related modes |
| 2395 | (no-case-fold-search) |
| 2396 | ) |
| 2397 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) |
| 2398 | @end example |
| 2399 | |
| 2400 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2401 | @node Style Variables, Styles, CC Hooks, Config Basics |
| 2402 | @comment node-name, next, previous, up |
| 2403 | @section Style Variables |
| 2404 | @cindex styles |
| 2405 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2406 | |
| 2407 | @cindex style variables |
| 2408 | The variables that @ccmode{}'s style system control are called |
| 2409 | @dfn{style variables}. Note that style variables are ordinary Lisp |
| 2410 | variables, which the style system initializes; you can change their |
| 2411 | values at any time (e.g. in a hook function). The style system can |
| 2412 | also set other variables, to some extent. @xref{Styles}. |
| 2413 | |
| 2414 | @dfn{Style variables} are handled specially in several ways: |
| 2415 | |
| 2416 | @itemize @bullet |
| 2417 | @item |
| 2418 | Style variables are by default buffer-local variables. However, they |
| 2419 | can instead be made global by setting |
| 2420 | @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is |
| 2421 | initialized. |
| 2422 | |
| 2423 | @item |
| 2424 | @vindex c-old-style-variable-behavior |
| 2425 | @vindex old-style-variable-behavior (c-) |
| 2426 | The default global binding of any style variable (with two exceptions |
| 2427 | - see below) is the special symbol @code{set-from-style}. When the |
| 2428 | style system initializes a buffer-local copy of a style variable for a |
| 2429 | @ccmode{} buffer, if its global binding is still that symbol then it |
| 2430 | will be set from the current style. Otherwise it will retain its |
| 2431 | global default@footnote{This is a big change from versions of |
| 2432 | @ccmode{} earlier than 5.26, where such settings would get overridden |
| 2433 | by the style system unless special precautions were taken. That was |
| 2434 | changed since it was counterintuitive and confusing, especially to |
| 2435 | novice users. If your configuration depends on the old overriding |
| 2436 | behavior, you can set the variable |
| 2437 | @code{c-old-style-variable-behavior} to non-@code{nil}.}. This |
| 2438 | ``otherwise'' happens, for example, when you've set the variable with |
| 2439 | @code{setq} at the top level of your @file{.emacs} (@pxref{Config |
| 2440 | Basics}). |
| 2441 | |
| 2442 | @item |
| 2443 | The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is |
| 2444 | an association list with an element for each syntactic symbol. It's |
| 2445 | handled a little differently from the other style variables. It's |
| 2446 | default global binding is the empty list @code{nil}, rather than |
| 2447 | @code{set-from-style}. Before the style system is initialized, you |
| 2448 | can add individual elements to @code{c-offsets-alist} by calling |
| 2449 | @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set |
| 2450 | other style variables with @code{setq}. Those elements will then |
| 2451 | prevail when the style system later initializes a buffer-local copy of |
| 2452 | @code{c-offsets-alist}. |
| 2453 | |
| 2454 | @item |
| 2455 | The style variable @code{c-special-indent-hook} is also handled in a |
| 2456 | special way. Styles can only add functions to this hook, not remove |
| 2457 | them, so any global settings you put on it are always |
| 2458 | preserved@footnote{This did not change in version 5.26.}. The value |
| 2459 | you give this variable in a style definition can be either a function |
| 2460 | or a list of functions. |
| 2461 | |
| 2462 | @item |
| 2463 | The global bindings of the style variables get captured in the special |
| 2464 | @code{user} style when the style system is first initialized. |
| 2465 | @xref{Built-in Styles}, for details. |
| 2466 | @end itemize |
| 2467 | |
| 2468 | The style variables are:@* |
| 2469 | @code{c-indent-comment-alist}, |
| 2470 | @code{c-indent-comments-syntactically-p} (@pxref{Indentation |
| 2471 | Commands});@* |
| 2472 | @code{c-doc-comment-style} (@pxref{Doc Comments});@* |
| 2473 | @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} |
| 2474 | (@pxref{Custom Filling and Breaking});@* |
| 2475 | @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* |
| 2476 | @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* |
| 2477 | @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and |
| 2478 | Commas});@* |
| 2479 | @code{c-cleanup-list} (@pxref{Clean-ups});@* |
| 2480 | @code{c-basic-offset} (@pxref{Customizing Indentation});@* |
| 2481 | @code{c-offsets-alist} (@pxref{c-offsets-alist});@* |
| 2482 | @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* |
| 2483 | @code{c-special-indent-hook}, @code{c-label-minimum-indentation} |
| 2484 | (@pxref{Other Indentation});@* |
| 2485 | @code{c-backslash-column}, @code{c-backslash-max-column} |
| 2486 | (@pxref{Custom Macros}). |
| 2487 | |
| 2488 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2489 | @node Styles, , Style Variables, Config Basics |
| 2490 | @comment node-name, next, previous, up |
| 2491 | @section Styles |
| 2492 | @cindex styles |
| 2493 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2494 | |
| 2495 | By @dfn{style} we mean the layout of the code---things like how many |
| 2496 | columns to indent a block of code, whether an opening brace gets |
| 2497 | indented to the level of the code it encloses, or of the construct |
| 2498 | that introduces it, or ``hangs'' at the end of a line. |
| 2499 | |
| 2500 | Most people only need to edit code formatted in just a few well-defined |
| 2501 | and consistent styles. For example, their organization might impose a |
| 2502 | ``blessed'' style that all its programmers must conform to. Similarly, |
| 2503 | people who work on GNU software will have to use the GNU coding style. |
| 2504 | Some shops are more lenient, allowing a variety of coding styles, and as |
| 2505 | programmers come and go, there could be a number of styles in use. For |
| 2506 | this reason, @ccmode{} makes it convenient for you to set up logical |
| 2507 | groupings of customizations called @dfn{styles}, associate a single name |
| 2508 | for any particular style, and pretty easily start editing new or |
| 2509 | existing code using these styles. |
| 2510 | |
| 2511 | @menu |
| 2512 | * Built-in Styles:: |
| 2513 | * Choosing a Style:: |
| 2514 | * Adding Styles:: |
| 2515 | * File Styles:: |
| 2516 | @end menu |
| 2517 | |
| 2518 | |
| 2519 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2520 | @node Built-in Styles, Choosing a Style, Styles, Styles |
| 2521 | @comment node-name, next, previous, up |
| 2522 | @subsection Built-in Styles |
| 2523 | @cindex styles, built-in |
| 2524 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2525 | |
| 2526 | If you're lucky, one of @ccmode{}'s built-in styles might be just |
| 2527 | what you're looking for. These are: |
| 2528 | |
| 2529 | @table @code |
| 2530 | @item gnu |
| 2531 | @cindex GNU style |
| 2532 | Coding style blessed by the Free Software Foundation |
| 2533 | for C code in GNU programs. |
| 2534 | |
| 2535 | @item k&r |
| 2536 | @cindex K&R style |
| 2537 | The classic Kernighan and Ritchie style for C code. |
| 2538 | |
| 2539 | @item bsd |
| 2540 | @cindex BSD style |
| 2541 | Also known as ``Allman style'' after Eric Allman. |
| 2542 | |
| 2543 | @item whitesmith |
| 2544 | @cindex Whitesmith style |
| 2545 | Popularized by the examples that came with Whitesmiths C, an early |
| 2546 | commercial C compiler. |
| 2547 | |
| 2548 | @item stroustrup |
| 2549 | @cindex Stroustrup style |
| 2550 | The classic Stroustrup style for C++ code. |
| 2551 | |
| 2552 | @item ellemtel |
| 2553 | @cindex Ellemtel style |
| 2554 | Popular C++ coding standards as defined by ``Programming in C++, Rules |
| 2555 | and Recommendations,'' Erik Nyquist and Mats Henricson, |
| 2556 | Ellemtel@footnote{This document is available at |
| 2557 | @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other |
| 2558 | places.}. |
| 2559 | @c N.B. This URL was still valid at 2005/8/28 (ACM). |
| 2560 | |
| 2561 | @item linux |
| 2562 | @cindex Linux style |
| 2563 | C coding standard for Linux (the kernel). |
| 2564 | |
| 2565 | @item python |
| 2566 | @cindex Python style |
| 2567 | C coding standard for Python extension modules@footnote{Python is a |
| 2568 | high level scripting language with a C/C++ foreign function interface. |
| 2569 | For more information, see @uref{http://www.python.org/}.}. |
| 2570 | |
| 2571 | @item java |
| 2572 | @cindex Java style |
| 2573 | The style for editing Java code. Note that the default |
| 2574 | value for @code{c-default-style} installs this style when you enter |
| 2575 | @code{java-mode}. |
| 2576 | |
| 2577 | @item awk |
| 2578 | @cindex AWK style |
| 2579 | The style for editing AWK code. Note that the default value for |
| 2580 | @code{c-default-style} installs this style when you enter |
| 2581 | @code{awk-mode}. |
| 2582 | |
| 2583 | @item user |
| 2584 | @cindex User style |
| 2585 | This is a special style created by you. It consists of the factory |
| 2586 | defaults for all the style variables as modified by the customizations |
| 2587 | you do either with the Customization interface or by writing |
| 2588 | @code{setq}s and @code{c-set-offset}s at the top level of your |
| 2589 | @file{.emacs} file (@pxref{Config Basics}). The style system creates |
| 2590 | this style as part of its initialization and doesn't modify it |
| 2591 | afterwards. |
| 2592 | @end table |
| 2593 | |
| 2594 | |
| 2595 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2596 | @node Choosing a Style, Adding Styles, Built-in Styles, Styles |
| 2597 | @comment node-name, next, previous, up |
| 2598 | @subsection Choosing a Style |
| 2599 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2600 | |
| 2601 | When you create a new buffer, its style will be set from |
| 2602 | @code{c-default-style}. The factory default is the style @code{gnu}, |
| 2603 | except in Java and AWK modes where it's @code{java} and @code{awk}. |
| 2604 | |
| 2605 | Remember that if you set a style variable with the Customization |
| 2606 | interface or at the top level of your @file{.emacs} file before the |
| 2607 | style system is initialised (@pxref{Config Basics}), this setting will |
| 2608 | override the one that the style system would have given the variable. |
| 2609 | |
| 2610 | To set a buffer's style interactively, use the command @kbd{C-c .} |
| 2611 | (@pxref{Other Commands}). To set it from a file's local variable |
| 2612 | list, @ref{File Styles}. |
| 2613 | |
| 2614 | @defopt c-default-style |
| 2615 | @vindex default-style (c-) |
| 2616 | This variable specifies which style to install by default in new |
| 2617 | buffers. It takes either a style name string, or an association list |
| 2618 | of major mode symbols to style names: |
| 2619 | |
| 2620 | @enumerate |
| 2621 | @item |
| 2622 | When @code{c-default-style} is a string, it must be an existing style |
| 2623 | name. This style is then used for all modes. |
| 2624 | |
| 2625 | @item |
| 2626 | When @code{c-default-style} is an association list, the mode language |
| 2627 | is looked up to find a style name string. |
| 2628 | |
| 2629 | @item |
| 2630 | If @code{c-default-style} is an association list where the mode |
| 2631 | language mode isn't found then the special symbol @samp{other} is |
| 2632 | looked up. If it's found then the associated style is used. |
| 2633 | |
| 2634 | @item |
| 2635 | If @samp{other} is not found then the @samp{gnu} style is used. |
| 2636 | @end enumerate |
| 2637 | |
| 2638 | In all cases, the style described in @code{c-default-style} is installed |
| 2639 | @emph{before} the language hooks are run, so you can always override |
| 2640 | this setting by including an explicit call to @code{c-set-style} in your |
| 2641 | language mode hook, or in @code{c-mode-common-hook}. |
| 2642 | |
| 2643 | The standard value of @code{c-default-style} is @w{@code{((java-mode |
| 2644 | . "java") (awk-mode . "awk") (other . "gnu"))}}. |
| 2645 | @end defopt |
| 2646 | |
| 2647 | @defvar c-indentation-style |
| 2648 | @vindex indentation-style (c-) |
| 2649 | This variable always contains the buffer's current style name, as a |
| 2650 | string. |
| 2651 | @end defvar |
| 2652 | |
| 2653 | |
| 2654 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2655 | @node Adding Styles, File Styles, Choosing a Style, Styles |
| 2656 | @comment node-name, next, previous, up |
| 2657 | @subsection Adding and Amending Styles |
| 2658 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2659 | |
| 2660 | If none of the built-in styles is appropriate, you'll probably want to |
| 2661 | create a new @dfn{style definition}, possibly based on an existing |
| 2662 | style. To do this, put the new style's settings into a list with the |
| 2663 | following format - the list can then be passed as an argument to the |
| 2664 | function @code{c-add-style}. You can see an example of a style |
| 2665 | definition in @ref{Sample .emacs File}. |
| 2666 | |
| 2667 | @cindex style definition |
| 2668 | @c @defvr {List} style definition |
| 2669 | @table @asis |
| 2670 | @item Structure of a Style Definition List |
| 2671 | ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) |
| 2672 | |
| 2673 | Optional @var{base-style}, if present, must be a string which is the |
| 2674 | name of the @dfn{base style} from which this style inherits. At most |
| 2675 | one @var{base-style} is allowed in a style definition. If |
| 2676 | @var{base-style} is not specified, the style inherits from the table |
| 2677 | of factory default values@footnote{This table is stored internally in |
| 2678 | the variable c-fallback-style.} instead. All styles eventually |
| 2679 | inherit from this internal table. Style loops generate errors. The |
| 2680 | list of pre-existing styles can be seen in @ref{Built-in Styles}. |
| 2681 | |
| 2682 | The dotted pairs (@var{variable} . @var{value}) each consist of a |
| 2683 | variable and the value it is to be set to when the style is later |
| 2684 | activated.@footnote{Note that if the variable has been given a value |
| 2685 | by the Customization interface or a @code{setq} at the top level of |
| 2686 | your @file{.emacs}, this value will override the one the style system |
| 2687 | tries to give it. @xref{Config Basics}.} The variable can be either a |
| 2688 | @ccmode{} style variable or an arbitrary Emacs variable. In the |
| 2689 | latter case, it is @emph{not} made buffer-local by the @ccmode{} style |
| 2690 | system. |
| 2691 | @c @end defvr |
| 2692 | |
| 2693 | Two variables are treated specially in the dotted pair list: |
| 2694 | |
| 2695 | @table @code |
| 2696 | @item c-offsets-alist |
| 2697 | The value is in turn a list of dotted pairs of the form |
| 2698 | |
| 2699 | @example |
| 2700 | (@r{@var{syntactic-symbol}} . @r{@var{offset}}) |
| 2701 | @end example |
| 2702 | |
| 2703 | as described in @ref{c-offsets-alist}. These are passed to |
| 2704 | @code{c-set-offset} so there is no need to set every syntactic symbol |
| 2705 | in your style, only those that are different from the inherited style. |
| 2706 | |
| 2707 | @item c-special-indent-hook |
| 2708 | The value is added to @code{c-special-indent-hook} using |
| 2709 | @code{add-hook}, so any functions already on it are kept. If the value |
| 2710 | is a list, each element of the list is added with @code{add-hook}. |
| 2711 | @end table |
| 2712 | @end table |
| 2713 | |
| 2714 | Styles are kept in the @code{c-style-alist} variable, but you |
| 2715 | should never modify this variable directly. Instead, @ccmode{} |
| 2716 | provides the function @code{c-add-style} for this purpose. |
| 2717 | |
| 2718 | @defun c-add-style stylename description &optional set-p |
| 2719 | @findex add-style (c-) |
| 2720 | Add or update a style called @var{stylename}, a string. |
| 2721 | @var{description} is the new style definition in the form described |
| 2722 | above. If @var{stylename} already exists in @code{c-style-alist} then |
| 2723 | it is replaced by @var{description}. (Note, this replacement is |
| 2724 | total. The old style is @emph{not} merged into the new one.) |
| 2725 | Otherwise, a new style is added. |
| 2726 | |
| 2727 | If the optional @var{set-p} is non-@code{nil} then the new style is |
| 2728 | applied to the current buffer as well. The use of this facility is |
| 2729 | deprecated and it might be removed from @ccmode{} in a future release. |
| 2730 | You should use @code{c-set-style} instead. |
| 2731 | |
| 2732 | The sample @file{.emacs} file provides a concrete example of how a new |
| 2733 | style can be added and automatically set. @xref{Sample .emacs File}. |
| 2734 | @end defun |
| 2735 | |
| 2736 | @defvar c-style-alist |
| 2737 | @vindex style-alist (c-) |
| 2738 | This is the variable that holds the definitions for the styles. It |
| 2739 | should not be changed directly; use @code{c-add-style} instead. |
| 2740 | @end defvar |
| 2741 | |
| 2742 | |
| 2743 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2744 | @node File Styles, , Adding Styles, Styles |
| 2745 | @comment node-name, next, previous, up |
| 2746 | @subsection File Styles |
| 2747 | @cindex styles, file local |
| 2748 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2749 | |
| 2750 | @cindex file local variables |
| 2751 | |
| 2752 | The Emacs manual describes how you can customize certain variables on a |
| 2753 | per-file basis by including a @dfn{file local variable} block at the end |
| 2754 | of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, |
| 2755 | @emacsmantitle{}}). |
| 2756 | |
| 2757 | So far, you've only seen a functional interface for setting styles in |
| 2758 | @ccmode{}, and this can't be used here. @ccmode{} fills the gap by |
| 2759 | providing two variables for use in a file's local variable list. |
| 2760 | Don't use them anywhere else! These allow you to customize the style |
| 2761 | on a per-file basis: |
| 2762 | |
| 2763 | @defvar c-file-style |
| 2764 | @vindex file-style (c-) |
| 2765 | Set this variable to a style name string in the Local Variables list. |
| 2766 | From now on, when you visit the file, @ccmode{} will automatically set |
| 2767 | the file's style to this one using @code{c-set-style}. |
| 2768 | @end defvar |
| 2769 | |
| 2770 | @defvar c-file-offsets |
| 2771 | @vindex file-offsets (c-) |
| 2772 | Set this variable (in the Local Variables list) to an association list |
| 2773 | of the same format as @code{c-offsets-alist}. From now on, when you |
| 2774 | visit the file, @ccmode{} will automatically institute these offsets |
| 2775 | using @code{c-set-offset}. |
| 2776 | @end defvar |
| 2777 | |
| 2778 | Note that file style settings (i.e. @code{c-file-style}) are applied |
| 2779 | before file offset settings |
| 2780 | (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set |
| 2781 | in a file's local variable section, all the style variable values are |
| 2782 | made local to that buffer, even if |
| 2783 | @code{c-style-variables-are-local-p} is @code{nil}. Since this |
| 2784 | variable is virtually always non-@code{nil} anyhow, you're unlikely to |
| 2785 | notice this effect.}. |
| 2786 | |
| 2787 | If you set any variables, including style variables, by the file local |
| 2788 | variables mechanism, these settings take priority over all other |
| 2789 | settings, even those in your mode hooks (@pxref{CC Hooks}). If you |
| 2790 | use @code{c-file-style} or @code{c-file-offsets} and also explicitly |
| 2791 | set a style variable in a local variable block, the explicit setting |
| 2792 | will take priority. |
| 2793 | |
| 2794 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2795 | @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top |
| 2796 | @comment node-name, next, previous, up |
| 2797 | @chapter Customizing Filling and Line Breaking |
| 2798 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 2799 | |
| 2800 | Since there's a lot of normal text in comments and string literals, |
| 2801 | @ccmode{} provides features to edit these like in text mode. It does |
| 2802 | this by hooking in on the different line breaking functions and tuning |
| 2803 | relevant variables as necessary. |
| 2804 | |
| 2805 | @vindex c-comment-prefix-regexp |
| 2806 | @vindex comment-prefix-regexp (c-) |
| 2807 | @cindex comment line prefix |
| 2808 | @vindex comment-start |
| 2809 | @vindex comment-end |
| 2810 | @vindex comment-start-skip |
| 2811 | @vindex paragraph-start |
| 2812 | @vindex paragraph-separate |
| 2813 | @vindex paragraph-ignore-fill-prefix |
| 2814 | @vindex adaptive-fill-mode |
| 2815 | @vindex adaptive-fill-regexp |
| 2816 | @vindex adaptive-fill-first-line-regexp |
| 2817 | To make Emacs recognize comments and treat text in them as normal |
| 2818 | paragraphs, @ccmode{} makes several standard |
| 2819 | variables@footnote{@code{comment-start}, @code{comment-end}, |
| 2820 | @code{comment-start-skip}, @code{paragraph-start}, |
| 2821 | @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, |
| 2822 | @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and |
| 2823 | @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them |
| 2824 | according to the language syntax and the comment line prefix. |
| 2825 | |
| 2826 | @defopt c-comment-prefix-regexp |
| 2827 | @vindex comment-prefix-regexp (c-) |
| 2828 | This style variable contains the regexp used to recognize the |
| 2829 | @dfn{comment line prefix}, which is the line decoration that starts |
| 2830 | every line in a comment. The variable is either the comment line |
| 2831 | prefix itself, or (more usually) an association list with different |
| 2832 | values for different languages. The symbol for the major mode is |
| 2833 | looked up in the alist to get the regexp for the language, and if it |
| 2834 | isn't found then the special symbol @samp{other} is looked up instead. |
| 2835 | |
| 2836 | When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} |
| 2837 | inserts the comment line prefix from a neighbouring line at the start |
| 2838 | of the new line. The default value of c-comment-prefix-regexp is |
| 2839 | @samp{//+\\|\\**}, which matches C++ style line comments like |
| 2840 | |
| 2841 | @example |
| 2842 | // blah blah |
| 2843 | @end example |
| 2844 | |
| 2845 | @noindent |
| 2846 | with two or more slashes in front of them, and the second and |
| 2847 | subsequent lines of C style block comments like |
| 2848 | |
| 2849 | @example |
| 2850 | @group |
| 2851 | /* |
| 2852 | * blah blah |
| 2853 | */ |
| 2854 | @end group |
| 2855 | @end example |
| 2856 | |
| 2857 | @noindent |
| 2858 | with zero or more stars at the beginning of every line. If you change |
| 2859 | this variable, please make sure it still matches the comment starter |
| 2860 | (i.e. @code{//}) of line comments @emph{and} the line prefix inside |
| 2861 | block comments. |
| 2862 | |
| 2863 | @findex c-setup-paragraph-variables |
| 2864 | @findex setup-paragraph-variables (c-) |
| 2865 | Also note that since @ccmode{} uses the value of |
| 2866 | @code{c-comment-prefix-regexp} to set up several other variables at |
| 2867 | mode initialization, there won't be any effect if you just change it |
| 2868 | inside a @ccmode{} buffer. You need to call the command |
| 2869 | @code{c-setup-paragraph-variables} too, to update those other |
| 2870 | variables. That's also the case if you modify |
| 2871 | @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will |
| 2872 | already have set up these variables before calling the hook. |
| 2873 | @end defopt |
| 2874 | |
| 2875 | In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt |
| 2876 | the line prefix from the other lines in the comment. |
| 2877 | |
| 2878 | @vindex adaptive-fill-mode |
| 2879 | @cindex Adaptive Fill mode |
| 2880 | @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU |
| 2881 | Emacs Manual}) to make Emacs correctly keep the line prefix when |
| 2882 | filling paragraphs. That also makes Emacs preserve the text |
| 2883 | indentation @emph{inside} the comment line prefix. E.g. in the |
| 2884 | following comment, both paragraphs will be filled with the left |
| 2885 | margins of the texts kept intact: |
| 2886 | |
| 2887 | @example |
| 2888 | @group |
| 2889 | /* Make a balanced b-tree of the nodes in the incoming |
| 2890 | * stream. But, to quote the famous words of Donald E. |
| 2891 | * Knuth, |
| 2892 | * |
| 2893 | * Beware of bugs in the above code; I have only |
| 2894 | * proved it correct, not tried it. |
| 2895 | */ |
| 2896 | @end group |
| 2897 | @end example |
| 2898 | |
| 2899 | @findex c-setup-filladapt |
| 2900 | @findex setup-filladapt (c-) |
| 2901 | @findex filladapt-mode |
| 2902 | @vindex filladapt-mode |
| 2903 | @cindex Filladapt mode |
| 2904 | It's also possible to use other adaptive filling packages, notably Kyle |
| 2905 | E. Jones' Filladapt package@footnote{It's available from |
| 2906 | @uref{http://www.wonderworks.com/}. As of version 2.12, it does however |
| 2907 | lack a feature that makes it work suboptimally when |
| 2908 | @code{c-comment-prefix-regexp} matches the empty string (which it does |
| 2909 | by default). A patch for that is available from |
| 2910 | @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, |
| 2911 | @c 2005/11/22: The above is still believed to be the case. |
| 2912 | which handles things like bulleted lists nicely. There's a convenience |
| 2913 | function @code{c-setup-filladapt} that tunes the relevant variables in |
| 2914 | Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with |
| 2915 | something like this in your @file{.emacs}: |
| 2916 | |
| 2917 | @example |
| 2918 | (defun my-c-mode-common-hook () |
| 2919 | (c-setup-filladapt) |
| 2920 | (filladapt-mode 1)) |
| 2921 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) |
| 2922 | @end example |
| 2923 | |
| 2924 | @defopt c-block-comment-prefix |
| 2925 | @vindex block-comment-prefix (c-) |
| 2926 | @vindex c-comment-continuation-stars |
| 2927 | @vindex comment-continuation-stars (c-) |
| 2928 | Normally the comment line prefix inserted for a new line inside a |
| 2929 | comment is deduced from other lines in it. However there's one |
| 2930 | situation when there's no hint about what the prefix should look like, |
| 2931 | namely when a block comment is broken for the first time. This style |
| 2932 | variable@footnote{In versions before 5.26, this variable was called |
| 2933 | @code{c-comment-continuation-stars}. As a compatibility measure, |
| 2934 | @ccmode{} still uses the value on that variable if it's set.} is used |
| 2935 | then as the comment prefix. It defaults to @samp{* |
| 2936 | }@footnote{Actually, this default setting of |
| 2937 | @code{c-block-comment-prefix} typically gets overridden by the default |
| 2938 | style @code{gnu}, which sets it to blank. You can see the line |
| 2939 | splitting effect described here by setting a different style, |
| 2940 | e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment |
| 2941 | |
| 2942 | @example |
| 2943 | /* Got O(n^2) here, which is a Bad Thing. */ |
| 2944 | @end example |
| 2945 | |
| 2946 | @noindent |
| 2947 | break into |
| 2948 | |
| 2949 | @example |
| 2950 | @group |
| 2951 | /* Got O(n^2) here, which |
| 2952 | * is a Bad Thing. */ |
| 2953 | @end group |
| 2954 | @end example |
| 2955 | |
| 2956 | Note that it won't work to adjust the indentation by putting leading |
| 2957 | spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the |
| 2958 | normal indentation engine to indent the line. Thus, the right way to |
| 2959 | fix the indentation is by customizing the @code{c} syntactic symbol. It |
| 2960 | defaults to @code{c-lineup-C-comments}, which handles the indentation of |
| 2961 | most common comment styles, see @ref{Line-Up Functions}. |
| 2962 | @end defopt |
| 2963 | |
| 2964 | @defopt c-ignore-auto-fill |
| 2965 | @vindex ignore-auto-fill (c-) |
| 2966 | When auto fill mode is enabled, @ccmode{} can selectively ignore it |
| 2967 | depending on the context the line break would occur in, e.g. to never |
| 2968 | break a line automatically inside a string literal. This variable |
| 2969 | takes a list of symbols for the different contexts where auto-filling |
| 2970 | never should occur: |
| 2971 | |
| 2972 | @table @code |
| 2973 | @item string |
| 2974 | Inside a string or character literal. |
| 2975 | @item c |
| 2976 | Inside a C style block comment. |
| 2977 | @item c++ |
| 2978 | Inside a C++ style line comment. |
| 2979 | @item cpp |
| 2980 | Inside a preprocessor directive. |
| 2981 | @item code |
| 2982 | Anywhere else, i.e. in normal code. |
| 2983 | @end table |
| 2984 | |
| 2985 | By default, @code{c-ignore-auto-fill} is set to @code{(string cpp |
| 2986 | code)}, which means that when auto-fill mode is activated, |
| 2987 | auto-filling only occurs in comments. In literals, it's often |
| 2988 | desirable to have explicit control over newlines. In preprocessor |
| 2989 | directives, the necessary @samp{\} escape character before the newline |
| 2990 | is not automatically inserted, so an automatic line break would |
| 2991 | produce invalid code. In normal code, line breaks are normally |
| 2992 | dictated by some logical structure in the code rather than the last |
| 2993 | whitespace character, so automatic line breaks there will produce poor |
| 2994 | results in the current implementation. |
| 2995 | @end defopt |
| 2996 | |
| 2997 | @vindex comment-multi-line |
| 2998 | If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, |
| 2999 | @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and |
| 3000 | line prefix are preserved. If inside a comment and |
| 3001 | @code{comment-multi-line} is @code{nil}, a new comment of the same |
| 3002 | type is started on the next line and indented as appropriate for |
| 3003 | comments. |
| 3004 | |
| 3005 | Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at |
| 3006 | startup. The reason is that @kbd{M-j} could otherwise produce sequences |
| 3007 | of single line block comments for texts that should logically be treated |
| 3008 | as one comment, and the rest of the paragraph handling code |
| 3009 | (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to |
| 3010 | inconsistent behavior. |
| 3011 | |
| 3012 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3013 | @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top |
| 3014 | @comment node-name, next, previous, up |
| 3015 | @chapter Customizing Auto-newlines |
| 3016 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3017 | |
| 3018 | @ccmode{} determines whether to insert auto-newlines in two basically |
| 3019 | different ways, depending on the character just typed: |
| 3020 | |
| 3021 | @table @asis |
| 3022 | @item Braces and Colons |
| 3023 | @ccmode{} first determines the syntactic context of the brace or colon |
| 3024 | (@pxref{Syntactic Symbols}), then looks for a corresponding element in |
| 3025 | an alist. This element specifies where to put newlines - this is any |
| 3026 | combination of before and after the brace or colon. If no alist |
| 3027 | element is found, newlines are inserted both before and after a brace, |
| 3028 | but none are inserted around a colon. See @ref{Hanging Braces} and |
| 3029 | @ref{Hanging Colons}. |
| 3030 | |
| 3031 | @item Semicolons and Commas |
| 3032 | The variable @code{c-hanging-semi&comma-criteria} contains a list of |
| 3033 | functions which determine whether to insert a newline after a newly |
| 3034 | typed semicolon or comma. @xref{Hanging Semicolons and Commas}. |
| 3035 | @end table |
| 3036 | |
| 3037 | The names of these configuration variables contain @samp{hanging} |
| 3038 | because they let you @dfn{hang} the pertinent characters. A character |
| 3039 | which introduces a C construct is said to @dfn{hang on the right} when |
| 3040 | it appears at the end of a line after other code, being separated by a |
| 3041 | line break from the construct it introduces, like the opening brace in: |
| 3042 | |
| 3043 | @example |
| 3044 | @group |
| 3045 | while (i < MAX) @{ |
| 3046 | total += entry[i]; |
| 3047 | entry [i++] = 0; |
| 3048 | @} |
| 3049 | @end group |
| 3050 | @end example |
| 3051 | |
| 3052 | @noindent |
| 3053 | A character @dfn{hangs on the left} when it appears at the start of |
| 3054 | the line after the construct it closes off, like the above closing |
| 3055 | brace. |
| 3056 | |
| 3057 | The next chapter, ``Clean-ups'', describes how to configure @ccmode{} |
| 3058 | to remove these automatically added newlines in certain specific |
| 3059 | circumstances. @xref{Clean-ups}. |
| 3060 | |
| 3061 | @menu |
| 3062 | * Hanging Braces:: |
| 3063 | * Hanging Colons:: |
| 3064 | * Hanging Semicolons and Commas:: |
| 3065 | @end menu |
| 3066 | |
| 3067 | |
| 3068 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3069 | @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines |
| 3070 | @comment node-name, next, previous, up |
| 3071 | @section Hanging Braces |
| 3072 | @cindex hanging braces |
| 3073 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3074 | |
| 3075 | To specify which kinds of braces you want auto-newlines put around, |
| 3076 | you set the style variable @code{c-hanging-braces-alist}. Its |
| 3077 | structure and semantics are described in this section. Details of how |
| 3078 | to set it up, and its relationship to CC Mode's style system are given |
| 3079 | in @ref{Style Variables}. |
| 3080 | |
| 3081 | Say you wanted an auto-newline after (but not before) the following |
| 3082 | @samp{@{}: |
| 3083 | |
| 3084 | @example |
| 3085 | if (foo < 17) @{ |
| 3086 | @end example |
| 3087 | |
| 3088 | @noindent |
| 3089 | First you need to find the @dfn{syntactic context} of the brace---type |
| 3090 | a @key{RET} before the brace to get it on a line of its |
| 3091 | own@footnote{Also insert a @samp{\} at the end of the previous line if |
| 3092 | you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you |
| 3093 | something like: |
| 3094 | |
| 3095 | @example |
| 3096 | ((substatement-open 1061)) |
| 3097 | @end example |
| 3098 | |
| 3099 | @noindent |
| 3100 | So here you need to put the entry @code{(substatement-open . (after))} |
| 3101 | into @code{c-hanging-braces-alist}. |
| 3102 | |
| 3103 | If you don't want any auto-newlines for a particular syntactic symbol, |
| 3104 | put this into @code{c-hanging-braces-alist}: |
| 3105 | |
| 3106 | @example |
| 3107 | (brace-entry-open) |
| 3108 | @end example |
| 3109 | |
| 3110 | If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, |
| 3111 | its entry is taken by default as @code{(before after)}---insert a |
| 3112 | newline both before and after the brace. In place of a |
| 3113 | ``before/after'' list you can specify a function in this alist---this |
| 3114 | is useful when the auto newlines depend on the code around the brace. |
| 3115 | |
| 3116 | @defopt c-hanging-braces-alist |
| 3117 | @vindex hanging-braces-alist (c-) |
| 3118 | |
| 3119 | This variable is an association list which maps syntactic symbols to |
| 3120 | lists of places to insert a newline. @xref{Association |
| 3121 | Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the |
| 3122 | syntactic symbol, the associated value is either @code{nil}, a list, |
| 3123 | or a function. |
| 3124 | |
| 3125 | @table @asis |
| 3126 | @item The Key - the syntactic symbol |
| 3127 | The syntactic symbols that are useful as keys in this list are |
| 3128 | @code{brace-list-intro}, @code{statement-cont}, |
| 3129 | @code{inexpr-class-open}, @code{inexpr-class-close}, and all the |
| 3130 | @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, |
| 3131 | for a more detailed description of these syntactic symbols, except for |
| 3132 | @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't |
| 3133 | actual syntactic symbols. Elements with any other value as a key get |
| 3134 | ignored. |
| 3135 | |
| 3136 | The braces of anonymous inner classes in Java are given the special |
| 3137 | symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that |
| 3138 | they can be distinguished from the braces of normal classes@footnote{The |
| 3139 | braces of anonymous classes produce a combination of |
| 3140 | @code{inexpr-class}, and @code{class-open} or @code{class-close} in |
| 3141 | normal indentation analysis.}. |
| 3142 | |
| 3143 | Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, |
| 3144 | @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace |
| 3145 | lists in this regard, even though they do for normal indentation |
| 3146 | purposes. It's currently not possible to set automatic newlines on |
| 3147 | these constructs. |
| 3148 | |
| 3149 | @item The associated value - the ``ACTION'' list or function |
| 3150 | The value associated with each syntactic symbol in this association |
| 3151 | list is called an @var{action}, which can be either a list or a |
| 3152 | function which returns a list. @xref{Custom Braces}, for how to use |
| 3153 | a function as a brace hanging @var{action}. |
| 3154 | |
| 3155 | The list @var{action} (or the list returned by @var{action} when it's |
| 3156 | a function) contains some combination of the symbols @code{before} and |
| 3157 | @code{after}, directing @ccmode{} where to put newlines in |
| 3158 | relationship to the brace being inserted. Thus, if the list contains |
| 3159 | only the symbol @code{after}, then the brace hangs on the right side |
| 3160 | of the line, as in: |
| 3161 | |
| 3162 | @example |
| 3163 | // here, open braces always `hang' |
| 3164 | void spam( int i ) @{ |
| 3165 | if( i == 7 ) @{ |
| 3166 | dosomething(i); |
| 3167 | @} |
| 3168 | @} |
| 3169 | @end example |
| 3170 | |
| 3171 | When the list contains both @code{after} and @code{before}, the braces |
| 3172 | will appear on a line by themselves, as shown by the close braces in |
| 3173 | the above example. The list can also be empty, in which case newlines |
| 3174 | are added neither before nor after the brace. |
| 3175 | @end table |
| 3176 | |
| 3177 | If a syntactic symbol is missing entirely from |
| 3178 | @code{c-hanging-braces-alist}, it's treated in the same way as an |
| 3179 | @var{action} with a list containing @code{before} and @code{after}, so |
| 3180 | that braces by default end up on their own line. |
| 3181 | |
| 3182 | For example, the default value of @code{c-hanging-braces-alist} is: |
| 3183 | |
| 3184 | @example |
| 3185 | ((brace-list-open) |
| 3186 | (brace-entry-open) |
| 3187 | (statement-cont) |
| 3188 | (substatement-open after) |
| 3189 | (block-close . c-snug-do-while) |
| 3190 | (extern-lang-open after) |
| 3191 | (namespace-open after) |
| 3192 | (module-open after) |
| 3193 | (composition-open after) |
| 3194 | (inexpr-class-open after) |
| 3195 | (inexpr-class-close before)) |
| 3196 | @end example |
| 3197 | |
| 3198 | @noindent which says that @code{brace-list-open}, |
| 3199 | @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists |
| 3200 | inside statements, such as initializers for static array variables |
| 3201 | inside functions in C, are recognized as @code{statement-cont}. All |
| 3202 | normal substatement blocks are recognized with other symbols.} braces |
| 3203 | should both hang on the right side and allow subsequent text to follow |
| 3204 | on the same line as the brace. Also, @code{substatement-open}, |
| 3205 | @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang |
| 3206 | on the right side, but subsequent text should follow on the next line. |
| 3207 | The opposite holds for @code{inexpr-class-close} braces; they won't |
| 3208 | hang, but the following text continues on the same line. Here, in the |
| 3209 | @code{block-close} entry, you also see an example of using a function as |
| 3210 | an @var{action}. In all other cases, braces are put on a line by |
| 3211 | themselves. |
| 3212 | @end defopt |
| 3213 | |
| 3214 | @menu |
| 3215 | * Custom Braces:: |
| 3216 | @end menu |
| 3217 | |
| 3218 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3219 | @node Custom Braces, , Hanging Braces, Hanging Braces |
| 3220 | @comment node-name, next, previous, up |
| 3221 | @subsection Custom Brace Hanging |
| 3222 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3223 | |
| 3224 | @vindex c-hanging-braces-alist |
| 3225 | @vindex hanging-braces-alist (c-) |
| 3226 | @cindex action functions |
| 3227 | Syntactic symbols aren't the only place where you can customize |
| 3228 | @ccmode{} with the lisp equivalent of callback functions. Remember |
| 3229 | that @var{action}s are usually a list containing some combination of |
| 3230 | the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). |
| 3231 | For more flexibility, you can instead specify brace ``hanginess'' by |
| 3232 | giving a syntactic symbol an @dfn{action function} in |
| 3233 | @code{c-hanging-braces-alist}; this function determines the |
| 3234 | ``hanginess'' of a brace, usually by looking at the code near it. |
| 3235 | |
| 3236 | @cindex customization, brace hanging |
| 3237 | An action function is called with two arguments: the syntactic symbol |
| 3238 | for the brace (e.g. @code{substatement-open}), and the buffer position |
| 3239 | where the brace has been inserted. Point is undefined on entry to an |
| 3240 | action function, but the function must preserve it (e.g. by using |
| 3241 | @code{save-excursion}). The return value should be a list containing |
| 3242 | some combination of @code{before} and @code{after}, including neither |
| 3243 | of them (i.e. @code{nil}). |
| 3244 | |
| 3245 | @defvar c-syntactic-context |
| 3246 | @vindex syntactic-context (c-) |
| 3247 | During the call to the indentation or brace hanging @var{action} |
| 3248 | function, this variable is bound to the full syntactic analysis list. |
| 3249 | This might be, for example, @samp{((block-close 73))}. Don't ever |
| 3250 | give @code{c-syntactic-context} a value yourself---this would disrupt |
| 3251 | the proper functioning of @ccmode{}. |
| 3252 | |
| 3253 | This variable is also bound in three other circumstances: |
| 3254 | (i)@w{ }when calling a c-hanging-semi&comma-criteria function |
| 3255 | (@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a |
| 3256 | line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a |
| 3257 | c-special-indent-hook function (@pxref{Other Indentation}). |
| 3258 | @end defvar |
| 3259 | |
| 3260 | As an example, @ccmode{} itself uses this feature to dynamically |
| 3261 | determine the hanginess of braces which close ``do-while'' |
| 3262 | constructs: |
| 3263 | |
| 3264 | @example |
| 3265 | void do_list( int count, char** atleast_one_string ) |
| 3266 | @{ |
| 3267 | int i=0; |
| 3268 | do @{ |
| 3269 | handle_string( atleast_one_string[i] ); |
| 3270 | i++; |
| 3271 | @} while( i < count ); |
| 3272 | @} |
| 3273 | @end example |
| 3274 | |
| 3275 | @ccmode{} assigns the @code{block-close} syntactic symbol to the |
| 3276 | brace that closes the @code{do} construct, and normally we'd like the |
| 3277 | line that follows a @code{block-close} brace to begin on a separate |
| 3278 | line. However, with ``do-while'' constructs, we want the |
| 3279 | @code{while} clause to follow the closing brace. To do this, we |
| 3280 | associate the @code{block-close} symbol with the @var{action} function |
| 3281 | @code{c-snug-do-while}: |
| 3282 | |
| 3283 | @example |
| 3284 | (defun c-snug-do-while (syntax pos) |
| 3285 | "Dynamically calculate brace hanginess for do-while statements." |
| 3286 | (save-excursion |
| 3287 | (let (langelem) |
| 3288 | (if (and (eq syntax 'block-close) |
| 3289 | (setq langelem (assq 'block-close c-syntactic-context)) |
| 3290 | (progn (goto-char (cdr langelem)) |
| 3291 | (if (= (following-char) ?@{) |
| 3292 | (forward-sexp -1)) |
| 3293 | (looking-at "\\<do\\>[^_]"))) |
| 3294 | '(before) |
| 3295 | '(before after))))) |
| 3296 | @end example |
| 3297 | |
| 3298 | @findex c-snug-do-while |
| 3299 | @findex snug-do-while (c-) |
| 3300 | This function simply looks to see if the brace closes a ``do-while'' |
| 3301 | clause and if so, returns the list @samp{(before)} indicating |
| 3302 | that a newline should be inserted before the brace, but not after it. |
| 3303 | In all other cases, it returns the list @samp{(before after)} so |
| 3304 | that the brace appears on a line by itself. |
| 3305 | |
| 3306 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3307 | @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines |
| 3308 | @comment node-name, next, previous, up |
| 3309 | @section Hanging Colons |
| 3310 | @cindex hanging colons |
| 3311 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3312 | |
| 3313 | @cindex customization, colon hanging |
| 3314 | @vindex c-hanging-colons-alist |
| 3315 | @vindex hanging-colons-alist (c-) |
| 3316 | |
| 3317 | Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), |
| 3318 | colons can also be made to hang using the style variable |
| 3319 | @code{c-hanging-colons-alist} - When a colon is typed, @ccmode |
| 3320 | determines its syntactic context, looks this up in the alist |
| 3321 | @code{c-changing-colons-alist} and inserts up to two newlines |
| 3322 | accordingly. Here, however, If @ccmode fails to find an entry for a |
| 3323 | syntactic symbol in the alist, no newlines are inserted around the |
| 3324 | newly typed colon. |
| 3325 | |
| 3326 | @defopt c-hanging-colons-alist |
| 3327 | @vindex hanging-colons-alist (c-) |
| 3328 | |
| 3329 | @table @asis |
| 3330 | @item The Key - the syntactic symbol |
| 3331 | The syntactic symbols appropriate as keys in this association list |
| 3332 | are: @code{case-label}, @code{label}, @code{access-label}, |
| 3333 | @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic |
| 3334 | Symbols}. Elements with any other value as a key get ignored. |
| 3335 | |
| 3336 | @item The associate value - the ``ACTION'' list |
| 3337 | The @var{action} here is simply a list containing a combination of the |
| 3338 | symbols @code{before} and @code{after}. Unlike in |
| 3339 | @code{c-hanging-braces-alist}, functions as @var{actions} are not |
| 3340 | supported - there doesn't seem to be any need for them. |
| 3341 | @end table |
| 3342 | @end defopt |
| 3343 | |
| 3344 | In C++, double-colons are used as a scope operator but because these |
| 3345 | colons always appear right next to each other, newlines before and after |
| 3346 | them are controlled by a different mechanism, called @dfn{clean-ups} in |
| 3347 | @ccmode{}. @xref{Clean-ups}, for details. |
| 3348 | |
| 3349 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3350 | @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines |
| 3351 | @comment node-name, next, previous, up |
| 3352 | @section Hanging Semicolons and Commas |
| 3353 | @cindex hanging semicolons |
| 3354 | @cindex hanging commas |
| 3355 | @cindex customization, semicolon newlines |
| 3356 | @cindex customization, comma newlines |
| 3357 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3358 | |
| 3359 | @defopt c-hanging-semi&comma-criteria |
| 3360 | @vindex hanging-semi&comma-criteria (c-) |
| 3361 | This style variable takes a list of functions; these get called when |
| 3362 | you type a semicolon or comma. The functions are called in order |
| 3363 | without arguments. When these functions are entered, point is just |
| 3364 | after the newly inserted @samp{;} or @samp{,} and they must preserve |
| 3365 | point (e.g., by using @code{save-excursion}). During the call, the |
| 3366 | variable @code{c-syntactic-context} is bound to the syntactic context |
| 3367 | of the current line@footnote{This was first introduced in @ccmode{} |
| 3368 | 5.31.} @pxref{Custom Braces}. These functions don't insert newlines |
| 3369 | themselves, rather they direct @ccmode{} whether or not to do so. |
| 3370 | They should return one of the following values: |
| 3371 | |
| 3372 | @table @code |
| 3373 | @item t |
| 3374 | A newline is to be inserted after the @samp{;} or @samp{,}, and no |
| 3375 | more functions from the list are to be called. |
| 3376 | @item stop |
| 3377 | No more functions from the list are to be called, and no newline is to |
| 3378 | be inserted. |
| 3379 | @item nil |
| 3380 | No determination has been made, and the next function in the list is |
| 3381 | to be called. |
| 3382 | @end table |
| 3383 | |
| 3384 | Note that auto-newlines are never inserted @emph{before} a semicolon |
| 3385 | or comma. If every function in the list is called without a |
| 3386 | determination being made, then no newline is added. |
| 3387 | |
| 3388 | In AWK mode, this variable is set by default to @code{nil}. In the |
| 3389 | other modes, the default value is a list containing a single function, |
| 3390 | @code{c-semi&comma-inside-parenlist}. This inserts newlines after all |
| 3391 | semicolons, apart from those separating @code{for}-clause statements. |
| 3392 | @end defopt |
| 3393 | |
| 3394 | @defun c-semi&comma-no-newlines-before-nonblanks |
| 3395 | @findex semi&comma-no-newlines-before-nonblanks (c-) |
| 3396 | This is an example of a criteria function, provided by @ccmode{}. It |
| 3397 | prevents newlines from being inserted after semicolons when there is a |
| 3398 | non-blank following line. Otherwise, it makes no determination. To |
| 3399 | use, add this function to the front of the |
| 3400 | @code{c-hanging-semi&comma-criteria} list. |
| 3401 | |
| 3402 | @example |
| 3403 | (defun c-semi&comma-no-newlines-before-nonblanks () |
| 3404 | (save-excursion |
| 3405 | (if (and (eq last-command-char ?\;) |
| 3406 | (zerop (forward-line 1)) |
| 3407 | (not (looking-at "^[ \t]*$"))) |
| 3408 | 'stop |
| 3409 | nil))) |
| 3410 | @end example |
| 3411 | @end defun |
| 3412 | |
| 3413 | @defun c-semi&comma-inside-parenlist |
| 3414 | @findex semi&comma-inside-parenlist (c-) |
| 3415 | @defunx c-semi&comma-no-newlines-for-oneline-inliners |
| 3416 | @findex semi&comma-no-newlines-for-oneline-inliners (c-) |
| 3417 | The function @code{c-semi&comma-inside-parenlist} is what prevents |
| 3418 | newlines from being inserted inside the parenthesis list of @code{for} |
| 3419 | statements. In addition to |
| 3420 | @code{c-semi&comma-no-newlines-before-nonblanks} described above, |
| 3421 | @ccmode{} also comes with the criteria function |
| 3422 | @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses |
| 3423 | newlines after semicolons inside one-line inline method definitions |
| 3424 | (e.g. in C++ or Java). |
| 3425 | @end defun |
| 3426 | |
| 3427 | |
| 3428 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3429 | @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top |
| 3430 | @comment node-name, next, previous, up |
| 3431 | @chapter Clean-ups |
| 3432 | @cindex clean-ups |
| 3433 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3434 | |
| 3435 | @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) |
| 3436 | whitespace in specific circumstances and are complementary to colon |
| 3437 | and brace hanging. You enable a clean-up by adding its symbol into |
| 3438 | @code{c-cleanup-list}, e.g. like this: |
| 3439 | |
| 3440 | @example |
| 3441 | (add-to-list 'c-cleanup-list 'space-before-funcall) |
| 3442 | @end example |
| 3443 | |
| 3444 | On the surface, it would seem that clean-ups overlap the functionality |
| 3445 | provided by the @code{c-hanging-*-alist} variables. Clean-ups, |
| 3446 | however, are used to adjust code ``after-the-fact'', i.e. to adjust |
| 3447 | the whitespace in constructs later than when they were typed. |
| 3448 | |
| 3449 | Most of the clean-ups remove automatically inserted newlines, and are |
| 3450 | only active when auto-newline minor mode is turned on. Others will |
| 3451 | work all the time. Note that clean-ups are only performed when there |
| 3452 | is nothing but whitespace appearing between the individual components |
| 3453 | of the construct, and (apart from @code{comment-close-slash}) when the |
| 3454 | construct does not occur within a literal (@pxref{Auto-newlines}). |
| 3455 | |
| 3456 | @defopt c-cleanup-list |
| 3457 | @vindex cleanup-list (c-) |
| 3458 | @cindex literal |
| 3459 | |
| 3460 | You configure @ccmode{}'s clean-ups by setting the style variable |
| 3461 | @code{c-cleanup-list}, which is a list of clean-up symbols. By |
| 3462 | default, @ccmode{} cleans up only the @code{scope-operator} construct, |
| 3463 | which is necessary for proper C++ support. |
| 3464 | @end defopt |
| 3465 | |
| 3466 | These are the clean-ups that are only active when electric and |
| 3467 | auto-newline minor modes are enabled: |
| 3468 | |
| 3469 | @c TBD: Would like to use some sort of @deffoo here; @table indents a |
| 3470 | @c bit too much in dvi output. |
| 3471 | @table @code |
| 3472 | @item brace-else-brace |
| 3473 | Clean up @samp{@} else @{} constructs by placing the entire construct on |
| 3474 | a single line. Clean up occurs when the open brace after the |
| 3475 | @samp{else} is typed. So for example, this: |
| 3476 | |
| 3477 | @example |
| 3478 | @group |
| 3479 | void spam(int i) |
| 3480 | @{ |
| 3481 | if( i==7 ) @{ |
| 3482 | dosomething(); |
| 3483 | @} |
| 3484 | else |
| 3485 | @{ |
| 3486 | @end group |
| 3487 | @end example |
| 3488 | |
| 3489 | @noindent |
| 3490 | appears like this after the last open brace is typed: |
| 3491 | |
| 3492 | @example |
| 3493 | @group |
| 3494 | void spam(int i) |
| 3495 | @{ |
| 3496 | if( i==7 ) @{ |
| 3497 | dosomething(); |
| 3498 | @} else @{ |
| 3499 | @end group |
| 3500 | @end example |
| 3501 | |
| 3502 | @item brace-elseif-brace |
| 3503 | Similar to the @code{brace-else-brace} clean-up, but this cleans up |
| 3504 | @samp{@} else if (...) @{} constructs. For example: |
| 3505 | |
| 3506 | @example |
| 3507 | @group |
| 3508 | void spam(int i) |
| 3509 | @{ |
| 3510 | if( i==7 ) @{ |
| 3511 | dosomething(); |
| 3512 | @} |
| 3513 | else if( i==3 ) |
| 3514 | @{ |
| 3515 | @end group |
| 3516 | @end example |
| 3517 | |
| 3518 | @noindent |
| 3519 | appears like this after the last open parenthesis is typed: |
| 3520 | |
| 3521 | @example |
| 3522 | @group |
| 3523 | void spam(int i) |
| 3524 | @{ |
| 3525 | if( i==7 ) @{ |
| 3526 | dosomething(); |
| 3527 | @} else if( |
| 3528 | @end group |
| 3529 | @end example |
| 3530 | |
| 3531 | @noindent |
| 3532 | and like this after the last open brace is typed: |
| 3533 | |
| 3534 | @example |
| 3535 | @group |
| 3536 | void spam(int i) |
| 3537 | @{ |
| 3538 | if( i==7 ) @{ |
| 3539 | dosomething(); |
| 3540 | @} else if( i==3 ) @{ |
| 3541 | @end group |
| 3542 | @end example |
| 3543 | |
| 3544 | @item brace-catch-brace |
| 3545 | Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch |
| 3546 | (...) @{} in C++ and Java mode. |
| 3547 | |
| 3548 | @item empty-defun-braces |
| 3549 | Clean up braces following a top-level function or class definition that |
| 3550 | contains no body. Clean up occurs when the closing brace is typed. |
| 3551 | Thus the following: |
| 3552 | |
| 3553 | @example |
| 3554 | @group |
| 3555 | class Spam |
| 3556 | @{ |
| 3557 | @} |
| 3558 | @end group |
| 3559 | @end example |
| 3560 | |
| 3561 | @noindent |
| 3562 | is transformed into this when the close brace is typed: |
| 3563 | |
| 3564 | @example |
| 3565 | @group |
| 3566 | class Spam |
| 3567 | @{@} |
| 3568 | @end group |
| 3569 | @end example |
| 3570 | |
| 3571 | @item defun-close-semi |
| 3572 | Clean up the terminating semicolon on top-level function or class |
| 3573 | definitions when they follow a close brace. Clean up occurs when the |
| 3574 | semicolon is typed. So for example, the following: |
| 3575 | |
| 3576 | @example |
| 3577 | @group |
| 3578 | class Spam |
| 3579 | @{ |
| 3580 | ... |
| 3581 | @} |
| 3582 | ; |
| 3583 | @end group |
| 3584 | @end example |
| 3585 | |
| 3586 | @noindent |
| 3587 | is transformed into this when the semicolon is typed: |
| 3588 | |
| 3589 | @example |
| 3590 | @group |
| 3591 | class Spam |
| 3592 | @{ |
| 3593 | ... |
| 3594 | @}; |
| 3595 | @end group |
| 3596 | @end example |
| 3597 | |
| 3598 | @item list-close-comma |
| 3599 | Clean up commas following braces in array and aggregate initializers. |
| 3600 | Clean up occurs when the comma is typed. The space before the comma |
| 3601 | is zapped just like the space before the semicolon in |
| 3602 | @code{defun-close-semi}. |
| 3603 | |
| 3604 | @item scope-operator |
| 3605 | Clean up double colons which might designate a C++ scope operator split |
| 3606 | across multiple lines@footnote{Certain C++ constructs introduce |
| 3607 | ambiguous situations, so @code{scope-operator} clean-ups might not |
| 3608 | always be correct. This usually only occurs when scoped identifiers |
| 3609 | appear in switch label tags.}. Clean up occurs when the second colon is |
| 3610 | typed. You will always want @code{scope-operator} in the |
| 3611 | @code{c-cleanup-list} when you are editing C++ code. |
| 3612 | |
| 3613 | @item one-liner-defun |
| 3614 | Clean up a single line of code enclosed by defun braces by removing |
| 3615 | the whitespace before and after the code. The clean-up happens when |
| 3616 | the closing brace is typed. If the variable |
| 3617 | @code{c-max-one-liner-length} is set, the cleanup is only done if the |
| 3618 | resulting line would be no longer than the value of that variable. |
| 3619 | |
| 3620 | For example, consider this AWK code: |
| 3621 | |
| 3622 | @example |
| 3623 | @group |
| 3624 | BEGIN @{ |
| 3625 | FS = "\t" # use <TAB> as a field separator |
| 3626 | @} |
| 3627 | @end group |
| 3628 | @end example |
| 3629 | |
| 3630 | @noindent |
| 3631 | It gets compacted to the following when the closing brace is typed: |
| 3632 | |
| 3633 | @example |
| 3634 | @group |
| 3635 | BEGIN @{FS = "\t"@} # use <TAB> as a field separator |
| 3636 | @end group |
| 3637 | @end example |
| 3638 | |
| 3639 | @defopt c-max-one-liner-length |
| 3640 | @vindex max-one-liner-length (c-) |
| 3641 | The maximum length of the resulting line for which the clean-up |
| 3642 | @code{one-liner-defun} will be triggered. This length is that of the entire |
| 3643 | line, including any leading whitespace and any trailing comment. Its |
| 3644 | default value is 80. If the value is zero or @code{nil}, no limit |
| 3645 | applies. |
| 3646 | @end defopt |
| 3647 | @end table |
| 3648 | |
| 3649 | The following clean-ups are always active when they occur on |
| 3650 | @code{c-cleanup-list}, regardless of whether Electric minor mode or |
| 3651 | Auto-newline minor mode are enabled: |
| 3652 | |
| 3653 | @table @code |
| 3654 | @item space-before-funcall |
| 3655 | Insert a space between the function name and the opening parenthesis |
| 3656 | of a function call. This produces function calls in the style |
| 3657 | mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, |
| 3658 | SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening |
| 3659 | parenthesis is typed. This clean-up should never be active in AWK |
| 3660 | Mode, since such a space is syntactically invalid for user defined |
| 3661 | functions. |
| 3662 | |
| 3663 | @item compact-empty-funcall |
| 3664 | Clean up any space between the function name and the opening parenthesis |
| 3665 | of a function call that has no arguments. This is typically used |
| 3666 | together with @code{space-before-funcall} if you prefer the GNU function |
| 3667 | call style for functions with arguments but think it looks ugly when |
| 3668 | it's only an empty parenthesis pair. I.e. you will get @samp{signal |
| 3669 | (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the |
| 3670 | closing parenthesis is typed. |
| 3671 | |
| 3672 | @item comment-close-slash |
| 3673 | When inside a block comment, terminate the comment when you type a slash |
| 3674 | at the beginning of a line (i.e. immediately after the comment prefix). |
| 3675 | This clean-up removes whitespace preceding the slash and if needed, |
| 3676 | inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this |
| 3677 | situation if you just want a literal @samp{/} inserted. |
| 3678 | @end table |
| 3679 | |
| 3680 | |
| 3681 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3682 | @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top |
| 3683 | @comment node-name, next, previous, up |
| 3684 | @chapter Indentation Engine Basics |
| 3685 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3686 | |
| 3687 | This chapter will briefly cover how @ccmode{} indents lines of code. |
| 3688 | It is helpful to understand the indentation model being used so that |
| 3689 | you will know how to customize @ccmode{} for your personal coding |
| 3690 | style. All the details are in @ref{Customizing Indentation}. |
| 3691 | |
| 3692 | @ccmode{} has an indentation engine that provides a flexible and |
| 3693 | general mechanism for customizing indentation. When @ccmode{} indents |
| 3694 | a line of code, it separates its calculations into two steps: |
| 3695 | |
| 3696 | @enumerate |
| 3697 | @item |
| 3698 | @cindex syntactic symbol |
| 3699 | @cindex anchor position |
| 3700 | It analyzes the line to determine its @dfn{syntactic symbol(s)} (the |
| 3701 | kind of language construct it's looking at) and its @dfn{anchor |
| 3702 | position} (the position earlier in the file that @ccmode{} will indent |
| 3703 | the line relative to). The anchor position might be the location of |
| 3704 | an opening brace in the previous line, for example. @xref{Syntactic |
| 3705 | Analysis}. |
| 3706 | @item |
| 3707 | @cindex offsets |
| 3708 | @cindex indentation offset specifications |
| 3709 | It looks up the syntactic symbol(s) in the configuration to get the |
| 3710 | corresponding @dfn{offset(s)}. The symbol @code{+}, which means |
| 3711 | ``indent this line one more level'' is a typical offset. @ccmode{} |
| 3712 | then applies these offset(s) to the anchor position, giving the |
| 3713 | indentation for the line. The different sorts of offsets are |
| 3714 | described in @ref{c-offsets-alist}. |
| 3715 | @end enumerate |
| 3716 | |
| 3717 | In exceptional circumstances, the syntax directed indentation |
| 3718 | described here may be a nuisance rather than a help. You can disable |
| 3719 | it by setting @code{c-syntactic-indentation} to @code{nil}. (To set |
| 3720 | the variable interactively, @ref{Minor Modes}). |
| 3721 | |
| 3722 | @defopt c-syntactic-indentation |
| 3723 | @vindex syntactic-indentation (c-) |
| 3724 | When this is non-@code{nil} (which it is by default), the indentation |
| 3725 | of code is done according to its syntactic structure. When it's |
| 3726 | @code{nil}, every line is just indented to the same level as the |
| 3727 | previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the |
| 3728 | indentation in steps of @code{c-basic-offset}. The current style |
| 3729 | (@pxref{Config Basics}) then has no effect on indentation, nor do any |
| 3730 | of the variables associated with indentation, not even |
| 3731 | @code{c-special-indent-hook}. |
| 3732 | @end defopt |
| 3733 | |
| 3734 | @menu |
| 3735 | * Syntactic Analysis:: |
| 3736 | * Syntactic Symbols:: |
| 3737 | * Indentation Calculation:: |
| 3738 | @end menu |
| 3739 | |
| 3740 | |
| 3741 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3742 | @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics |
| 3743 | @comment node-name, next, previous, up |
| 3744 | @section Syntactic Analysis |
| 3745 | @cindex syntactic analysis |
| 3746 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3747 | |
| 3748 | @cindex syntactic element |
| 3749 | @cindex syntactic context |
| 3750 | The first thing @ccmode{} does when indenting a line of code, is to |
| 3751 | analyze the line, determining the @dfn{syntactic context} of the |
| 3752 | (first) construct on that line. It's a list of @dfn{syntactic |
| 3753 | elements}, where each syntactic element in turn is a list@footnote{In |
| 3754 | @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the |
| 3755 | cons was the syntactic symbol and the cdr was the anchor position. |
| 3756 | For compatibility's sake, the parameter passed to a line-up function |
| 3757 | still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a |
| 3758 | brief and typical example: |
| 3759 | |
| 3760 | @example |
| 3761 | ((defun-block-intro 1959)) |
| 3762 | @end example |
| 3763 | |
| 3764 | @cindex syntactic symbol |
| 3765 | @noindent |
| 3766 | The first thing inside each syntactic element is always a |
| 3767 | @dfn{syntactic symbol}. It describes the kind of construct that was |
| 3768 | recognized, e.g. @code{statement}, @code{substatement}, |
| 3769 | @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, |
| 3770 | for a complete list of currently recognized syntactic symbols and |
| 3771 | their semantics. The remaining entries are various data associated |
| 3772 | with the recognized construct - there might be zero or more. |
| 3773 | |
| 3774 | @cindex anchor position |
| 3775 | Conceptually, a line of code is always indented relative to some |
| 3776 | position higher up in the buffer (typically the indentation of the |
| 3777 | previous line). That position is the @dfn{anchor position} in the |
| 3778 | syntactic element. If there is an entry after the syntactic symbol in |
| 3779 | the syntactic element list then it's either nil or that anchor position. |
| 3780 | |
| 3781 | Here is an example. Suppose we had the following code as the only thing |
| 3782 | in a C++ buffer @footnote{The line numbers in this and future examples |
| 3783 | don't actually appear in the buffer, of course!}: |
| 3784 | |
| 3785 | @example |
| 3786 | 1: void swap( int& a, int& b ) |
| 3787 | 2: @{ |
| 3788 | 3: int tmp = a; |
| 3789 | 4: a = b; |
| 3790 | 5: b = tmp; |
| 3791 | 6: @} |
| 3792 | @end example |
| 3793 | |
| 3794 | @noindent |
| 3795 | We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to |
| 3796 | report what the syntactic analysis is for the current line: |
| 3797 | |
| 3798 | @table @asis |
| 3799 | @item @kbd{C-c C-s} (@code{c-show-syntactic-information}) |
| 3800 | @kindex C-c C-s |
| 3801 | @findex c-show-syntactic-information |
| 3802 | @findex show-syntactic-information (c-) |
| 3803 | This command calculates the syntactic analysis of the current line and |
| 3804 | displays it in the minibuffer. The command also highlights the anchor |
| 3805 | position(s). |
| 3806 | @end table |
| 3807 | |
| 3808 | Running this command on line 4 of this example, we'd see in the echo |
| 3809 | area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the |
| 3810 | analysis is inserted into the buffer as a comment on the current |
| 3811 | line.}: |
| 3812 | |
| 3813 | @example |
| 3814 | ((statement 35)) |
| 3815 | @end example |
| 3816 | |
| 3817 | @noindent |
| 3818 | and the @samp{i} of @code{int} on line 3 would be highlighted. This |
| 3819 | tells us that the line is a statement and it is indented relative to |
| 3820 | buffer position 35, the highlighted position. If you were to move |
| 3821 | point to line 3 and hit @kbd{C-c C-s}, you would see: |
| 3822 | |
| 3823 | @example |
| 3824 | ((defun-block-intro 29)) |
| 3825 | @end example |
| 3826 | |
| 3827 | @noindent |
| 3828 | This indicates that the @samp{int} line is the first statement in a top |
| 3829 | level function block, and is indented relative to buffer position 29, |
| 3830 | which is the brace just after the function header. |
| 3831 | |
| 3832 | Here's another example: |
| 3833 | |
| 3834 | @example |
| 3835 | 1: int add( int val, int incr, int doit ) |
| 3836 | 2: @{ |
| 3837 | 3: if( doit ) |
| 3838 | 4: @{ |
| 3839 | 5: return( val + incr ); |
| 3840 | 6: @} |
| 3841 | 7: return( val ); |
| 3842 | 8: @} |
| 3843 | @end example |
| 3844 | |
| 3845 | @noindent |
| 3846 | Hitting @kbd{C-c C-s} on line 4 gives us: |
| 3847 | |
| 3848 | @example |
| 3849 | ((substatement-open 46)) |
| 3850 | @end example |
| 3851 | |
| 3852 | @cindex substatement |
| 3853 | @cindex substatement block |
| 3854 | @noindent |
| 3855 | which tells us that this is a brace that @emph{opens} a substatement |
| 3856 | block. @footnote{A @dfn{substatement} is the line after a |
| 3857 | conditional statement, such as @code{if}, @code{else}, @code{while}, |
| 3858 | @code{do}, @code{switch}, etc. A @dfn{substatement |
| 3859 | block} is a brace block following one of these conditional statements.} |
| 3860 | |
| 3861 | @cindex comment-only line |
| 3862 | Syntactic contexts can contain more than one element, and syntactic |
| 3863 | elements need not have anchor positions. The most common example of |
| 3864 | this is a @dfn{comment-only line}: |
| 3865 | |
| 3866 | @example |
| 3867 | 1: void draw_list( List<Drawables>& drawables ) |
| 3868 | 2: @{ |
| 3869 | 3: // call the virtual draw() method on each element in list |
| 3870 | 4: for( int i=0; i < drawables.count(), ++i ) |
| 3871 | 5: @{ |
| 3872 | 6: drawables[i].draw(); |
| 3873 | 7: @} |
| 3874 | 8: @} |
| 3875 | @end example |
| 3876 | |
| 3877 | @noindent |
| 3878 | Hitting @kbd{C-c C-s} on line 3 of this example gives: |
| 3879 | |
| 3880 | @example |
| 3881 | ((comment-intro) (defun-block-intro 46)) |
| 3882 | @end example |
| 3883 | |
| 3884 | @noindent |
| 3885 | and you can see that the syntactic context contains two syntactic |
| 3886 | elements. Notice that the first element, @samp{(comment-intro)}, has no |
| 3887 | anchor position. |
| 3888 | |
| 3889 | |
| 3890 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3891 | @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics |
| 3892 | @comment node-name, next, previous, up |
| 3893 | @section Syntactic Symbols |
| 3894 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 3895 | |
| 3896 | @cindex syntactic symbols, brief list |
| 3897 | @vindex c-offsets-alist |
| 3898 | @vindex offsets-alist (c-) |
| 3899 | This section is a complete list of the syntactic symbols which appear |
| 3900 | in the @code{c-offsets-alist} style variable, along with brief |
| 3901 | descriptions. The previous section (@pxref{Syntactic Analysis}) |
| 3902 | states what syntactic symbols are and how the indentation engine uses |
| 3903 | them. |
| 3904 | |
| 3905 | More detailed descriptions of these symbols, together with snippets of |
| 3906 | source code to which they apply, appear in the examples in the |
| 3907 | subsections below. Note that, in the interests of brevity, the anchor |
| 3908 | position associated with most syntactic symbols is @emph{not} |
| 3909 | specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent |
| 3910 | line---this highlights the anchor position. |
| 3911 | |
| 3912 | @ssindex -open symbols |
| 3913 | @ssindex -close symbols |
| 3914 | @ssindex -block-intro symbols |
| 3915 | The syntactic symbols which indicate brace constructs follow a general |
| 3916 | naming convention. When a line begins with an open or close brace, |
| 3917 | its syntactic symbol will contain the suffix @code{-open} or |
| 3918 | @code{-close} respectively. The first line within the brace block |
| 3919 | construct will contain the suffix @code{-block-intro}. |
| 3920 | |
| 3921 | @ssindex -intro symbols |
| 3922 | @ssindex -cont symbols |
| 3923 | In constructs which can span several lines, a distinction is usually |
| 3924 | made between the first line that introduces the construct and the |
| 3925 | lines that continue it. The syntactic symbols that indicate these |
| 3926 | lines will contain the suffixes @code{-intro} or @code{-cont} |
| 3927 | respectively. |
| 3928 | |
| 3929 | The best way to understand how all this works is by looking at some |
| 3930 | examples. Remember that you can see the syntax of any source code |
| 3931 | line by using @kbd{C-c C-s}. |
| 3932 | |
| 3933 | @table @code |
| 3934 | @item string |
| 3935 | Inside a multiline string. @ref{Literal Symbols}. |
| 3936 | @item c |
| 3937 | Inside a multiline C style block comment. @ref{Literal Symbols}. |
| 3938 | @item defun-open |
| 3939 | Brace that opens a top-level function definition. @ref{Function |
| 3940 | Symbols}. |
| 3941 | @item defun-close |
| 3942 | Brace that closes a top-level function definition. @ref{Function |
| 3943 | Symbols}. |
| 3944 | @item defun-block-intro |
| 3945 | The first line in a top-level defun. @ref{Function Symbols}. |
| 3946 | @item class-open |
| 3947 | Brace that opens a class definition. @ref{Class Symbols}. |
| 3948 | @item class-close |
| 3949 | Brace that closes a class definition. @ref{Class Symbols}. |
| 3950 | @item inline-open |
| 3951 | Brace that opens an in-class inline method. @ref{Class Symbols}. |
| 3952 | @item inline-close |
| 3953 | Brace that closes an in-class inline method. @ref{Class Symbols}. |
| 3954 | @item func-decl-cont |
| 3955 | The region between a function definition's argument list and the |
| 3956 | function opening brace (excluding K&R argument declarations). In C, |
| 3957 | you cannot put anything but whitespace and comments in this region, |
| 3958 | however in C++ and Java, @code{throws} declarations and other things |
| 3959 | can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not |
| 3960 | @c go somewhere better?} |
| 3961 | @item knr-argdecl-intro |
| 3962 | First line of a K&R C argument declaration. @ref{K&R Symbols}. |
| 3963 | @item knr-argdecl |
| 3964 | Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. |
| 3965 | @item topmost-intro |
| 3966 | The first line in a ``topmost'' definition. @ref{Function Symbols}. |
| 3967 | @item topmost-intro-cont |
| 3968 | Topmost definition continuation lines. This is only used in the parts |
| 3969 | that aren't covered by other symbols such as @code{func-decl-cont} and |
| 3970 | @code{knr-argdecl}. @ref{Function Symbols}. |
| 3971 | @item member-init-intro |
| 3972 | First line in a member initialization list. @ref{Class Symbols}. |
| 3973 | @item member-init-cont |
| 3974 | Subsequent member initialization list lines. @ref{Class Symbols}. |
| 3975 | @item inher-intro |
| 3976 | First line of a multiple inheritance list. @ref{Class Symbols}. |
| 3977 | @item inher-cont |
| 3978 | Subsequent multiple inheritance lines. @ref{Class Symbols}. |
| 3979 | @item block-open |
| 3980 | Statement block open brace. @ref{Literal Symbols}. |
| 3981 | @item block-close |
| 3982 | Statement block close brace. @ref{Conditional Construct Symbols}. |
| 3983 | @item brace-list-open |
| 3984 | Open brace of an enum or static array list. @ref{Brace List Symbols}. |
| 3985 | @item brace-list-close |
| 3986 | Close brace of an enum or static array list. @ref{Brace List Symbols}. |
| 3987 | @item brace-list-intro |
| 3988 | First line in an enum or static array list. @ref{Brace List Symbols}. |
| 3989 | @item brace-list-entry |
| 3990 | Subsequent lines in an enum or static array list. @ref{Brace List |
| 3991 | Symbols}. |
| 3992 | @item brace-entry-open |
| 3993 | Subsequent lines in an enum or static array list where the line begins |
| 3994 | with an open brace. @ref{Brace List Symbols}. |
| 3995 | @item statement |
| 3996 | A statement. @ref{Function Symbols}. |
| 3997 | @item statement-cont |
| 3998 | A continuation of a statement. @ref{Function Symbols}. |
| 3999 | @item statement-block-intro |
| 4000 | The first line in a new statement block. @ref{Conditional Construct |
| 4001 | Symbols}. |
| 4002 | @item statement-case-intro |
| 4003 | The first line in a case block. @ref{Switch Statement Symbols}. |
| 4004 | @item statement-case-open |
| 4005 | The first line in a case block that starts with a brace. @ref{Switch |
| 4006 | Statement Symbols}. |
| 4007 | @item substatement |
| 4008 | The first line after a conditional or loop construct. |
| 4009 | @ref{Conditional Construct Symbols}. |
| 4010 | @item substatement-open |
| 4011 | The brace that opens a substatement block. @ref{Conditional Construct |
| 4012 | Symbols}. |
| 4013 | @item substatement-label |
| 4014 | The first line after a conditional or loop construct if it's a label. |
| 4015 | @ref{Conditional Construct Symbols}. |
| 4016 | @item case-label |
| 4017 | A label in a @code{switch} block. @ref{Switch Statement Symbols}. |
| 4018 | @item access-label |
| 4019 | C++ access control label. @ref{Class Symbols}. |
| 4020 | @item label |
| 4021 | Any other label. @ref{Literal Symbols}. |
| 4022 | @item do-while-closure |
| 4023 | The @code{while} line that ends a @code{do}-@code{while} construct. |
| 4024 | @ref{Conditional Construct Symbols}. |
| 4025 | @item else-clause |
| 4026 | The @code{else} line of an @code{if}-@code{else} construct. |
| 4027 | @ref{Conditional Construct Symbols}. |
| 4028 | @item catch-clause |
| 4029 | The @code{catch} or @code{finally} (in Java) line of a |
| 4030 | @code{try}-@code{catch} construct. @ref{Conditional Construct |
| 4031 | Symbols}. |
| 4032 | @item comment-intro |
| 4033 | A line containing only a comment introduction. @ref{Literal Symbols}. |
| 4034 | @item arglist-intro |
| 4035 | The first line in an argument list. @ref{Paren List Symbols}. |
| 4036 | @item arglist-cont |
| 4037 | Subsequent argument list lines when no arguments follow on the same |
| 4038 | line as the arglist opening paren. @ref{Paren List Symbols}. |
| 4039 | @item arglist-cont-nonempty |
| 4040 | Subsequent argument list lines when at least one argument follows on |
| 4041 | the same line as the arglist opening paren. @ref{Paren List Symbols}. |
| 4042 | @item arglist-close |
| 4043 | The solo close paren of an argument list. @ref{Paren List Symbols}. |
| 4044 | @item stream-op |
| 4045 | Lines continuing a stream operator (C++ only). @ref{Literal |
| 4046 | Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} |
| 4047 | @item inclass |
| 4048 | The line is nested inside a class definition. @ref{Class Symbols}. |
| 4049 | @item cpp-macro |
| 4050 | The start of a preprocessor macro definition. @ref{Literal Symbols}. |
| 4051 | @item cpp-define-intro |
| 4052 | The first line inside a multiline preprocessor macro if |
| 4053 | @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro |
| 4054 | Symbols}. |
| 4055 | @item cpp-macro-cont |
| 4056 | All lines inside multiline preprocessor macros if |
| 4057 | @code{c-syntactic-indentation-in-macros} is @code{nil}. |
| 4058 | @ref{Multiline Macro Symbols}. |
| 4059 | @item friend |
| 4060 | A C++ friend declaration. @ref{Class Symbols}. |
| 4061 | @item objc-method-intro |
| 4062 | The first line of an Objective-C method definition. @ref{Objective-C |
| 4063 | Method Symbols}. |
| 4064 | @item objc-method-args-cont |
| 4065 | Lines continuing an Objective-C method definition. @ref{Objective-C |
| 4066 | Method Symbols}. |
| 4067 | @item objc-method-call-cont |
| 4068 | Lines continuing an Objective-C method call. @ref{Objective-C Method |
| 4069 | Symbols}. |
| 4070 | @item extern-lang-open |
| 4071 | Brace that opens an @code{extern} block (e.g. @code{extern "C" |
| 4072 | @{...@}}). @ref{External Scope Symbols}. |
| 4073 | @item extern-lang-close |
| 4074 | Brace that closes an @code{extern} block. @ref{External Scope |
| 4075 | Symbols}. |
| 4076 | @item inextern-lang |
| 4077 | Analogous to @code{inclass} syntactic symbol, but used inside |
| 4078 | @code{extern} blocks. @ref{External Scope Symbols}. |
| 4079 | @item namespace-open |
| 4080 | @itemx namespace-close |
| 4081 | @itemx innamespace |
| 4082 | These are analogous to the three @code{extern-lang} symbols above, but |
| 4083 | are returned for C++ namespace blocks. @ref{External Scope Symbols}. |
| 4084 | @item module-open |
| 4085 | @itemx module-close |
| 4086 | @itemx inmodule |
| 4087 | Analogous to the above, but for CORBA IDL @code{module} blocks. |
| 4088 | @ref{External Scope Symbols}. |
| 4089 | @item composition-open |
| 4090 | @itemx composition-close |
| 4091 | @itemx incomposition |
| 4092 | Analogous to the above, but for CORBA CIDL @code{composition} blocks. |
| 4093 | @ref{External Scope Symbols}. |
| 4094 | @item template-args-cont |
| 4095 | C++ template argument list continuations. @ref{Class Symbols}. |
| 4096 | @item inlambda |
| 4097 | Analogous to @code{inclass} syntactic symbol, but used inside lambda |
| 4098 | (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement |
| 4099 | Block Symbols}. |
| 4100 | @item lambda-intro-cont |
| 4101 | Lines continuing the header of a lambda function, i.e. between the |
| 4102 | @code{lambda} keyword and the function body. Only used in Pike mode. |
| 4103 | @ref{Statement Block Symbols}. |
| 4104 | @item inexpr-statement |
| 4105 | A statement block inside an expression. The gcc C and C++ extension |
| 4106 | for this is recognized. It's also used for the special functions that |
| 4107 | take a statement block as an argument in Pike. @ref{Statement Block |
| 4108 | Symbols}. |
| 4109 | @item inexpr-class |
| 4110 | A class definition inside an expression. This is used for anonymous |
| 4111 | classes in Java. It's also used for anonymous array initializers in |
| 4112 | Java. @ref{Anonymous Class Symbol}. |
| 4113 | @end table |
| 4114 | |
| 4115 | @menu |
| 4116 | * Function Symbols:: |
| 4117 | * Class Symbols:: |
| 4118 | * Conditional Construct Symbols:: |
| 4119 | * Switch Statement Symbols:: |
| 4120 | * Brace List Symbols:: |
| 4121 | * External Scope Symbols:: |
| 4122 | * Paren List Symbols:: |
| 4123 | * Literal Symbols:: |
| 4124 | * Multiline Macro Symbols:: |
| 4125 | * Objective-C Method Symbols:: |
| 4126 | * Anonymous Class Symbol:: |
| 4127 | * Statement Block Symbols:: |
| 4128 | * K&R Symbols:: |
| 4129 | @end menu |
| 4130 | |
| 4131 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4132 | @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols |
| 4133 | @comment node-name, next, previous, up |
| 4134 | @subsection Function Symbols |
| 4135 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4136 | |
| 4137 | This example shows a typical function declaration. |
| 4138 | |
| 4139 | @example |
| 4140 | 1: void |
| 4141 | 2: swap( int& a, int& b ) |
| 4142 | 3: @{ |
| 4143 | 4: int tmp = a; |
| 4144 | 5: a = b; |
| 4145 | 6: b = tmp; |
| 4146 | 7: int ignored = |
| 4147 | 8: a + b; |
| 4148 | 9: @} |
| 4149 | @end example |
| 4150 | |
| 4151 | @ssindex topmost-intro |
| 4152 | @ssindex topmost-intro-cont |
| 4153 | @ssindex defun-open |
| 4154 | @ssindex defun-close |
| 4155 | @ssindex defun-block-intro |
| 4156 | Line 1 shows a @code{topmost-intro} since it is the first line that |
| 4157 | introduces a top-level construct. Line 2 is a continuation of the |
| 4158 | top-level construct introduction so it has the syntax |
| 4159 | @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is |
| 4160 | the brace that opens a top-level function definition. Line 9 is the |
| 4161 | corresponding |
| 4162 | @code{defun-close} since it contains the brace that closes the top-level |
| 4163 | function definition. Line 4 is a @code{defun-block-intro}, i.e. it is |
| 4164 | the first line of a brace-block, enclosed in a |
| 4165 | top-level function definition. |
| 4166 | |
| 4167 | @ssindex statement |
| 4168 | @ssindex statement-cont |
| 4169 | Lines 5, 6, and 7 are all given @code{statement} syntax since there |
| 4170 | isn't much special about them. Note however that line 8 is given |
| 4171 | @code{statement-cont} syntax since it continues the statement begun |
| 4172 | on the previous line. |
| 4173 | |
| 4174 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4175 | @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols |
| 4176 | @comment node-name, next, previous, up |
| 4177 | @subsection Class related Symbols |
| 4178 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4179 | |
| 4180 | Here's an example which illustrates some C++ class syntactic symbols: |
| 4181 | |
| 4182 | @example |
| 4183 | 1: class Bass |
| 4184 | 2: : public Guitar, |
| 4185 | 3: public Amplifiable |
| 4186 | 4: @{ |
| 4187 | 5: public: |
| 4188 | 6: Bass() |
| 4189 | 7: : eString( new BassString( 0.105 )), |
| 4190 | 8: aString( new BassString( 0.085 )), |
| 4191 | 9: dString( new BassString( 0.065 )), |
| 4192 | 10: gString( new BassString( 0.045 )) |
| 4193 | 11: @{ |
| 4194 | 12: eString.tune( 'E' ); |
| 4195 | 13: aString.tune( 'A' ); |
| 4196 | 14: dString.tune( 'D' ); |
| 4197 | 15: gString.tune( 'G' ); |
| 4198 | 16: @} |
| 4199 | 17: friend class Luthier; |
| 4200 | 18: @}; |
| 4201 | @end example |
| 4202 | |
| 4203 | @ssindex class-open |
| 4204 | @ssindex class-close |
| 4205 | As in the previous example, line 1 has the @code{topmost-intro} syntax. |
| 4206 | Here however, the brace that opens a C++ class definition on line 4 is |
| 4207 | assigned the @code{class-open} syntax. Note that in C++, classes, |
| 4208 | structs, and unions are essentially equivalent syntactically (and are |
| 4209 | very similar semantically), so replacing the @code{class} keyword in the |
| 4210 | example above with @code{struct} or @code{union} would still result in a |
| 4211 | syntax of @code{class-open} for line 4 @footnote{This is the case even |
| 4212 | for C and Objective-C. For consistency, structs in all supported |
| 4213 | languages are syntactically equivalent to classes. Note however that |
| 4214 | the keyword @code{class} is meaningless in C and Objective-C.}. |
| 4215 | Similarly, line 18 is assigned @code{class-close} syntax. |
| 4216 | |
| 4217 | @ssindex inher-intro |
| 4218 | @ssindex inher-cont |
| 4219 | Line 2 introduces the inheritance list for the class so it is assigned |
| 4220 | the @code{inher-intro} syntax, and line 3, which continues the |
| 4221 | inheritance list is given @code{inher-cont} syntax. |
| 4222 | |
| 4223 | @ssindex access-label |
| 4224 | @ssindex inclass |
| 4225 | Hitting @kbd{C-c C-s} on line 5 shows the following analysis: |
| 4226 | |
| 4227 | @example |
| 4228 | ((inclass 58) (access-label 58)) |
| 4229 | @end example |
| 4230 | |
| 4231 | @noindent |
| 4232 | The primary syntactic symbol for this line is @code{access-label} as |
| 4233 | this a label keyword that specifies access protection in C++. However, |
| 4234 | because this line is also a top-level construct inside a class |
| 4235 | definition, the analysis actually shows two syntactic symbols. The |
| 4236 | other syntactic symbol assigned to this line is @code{inclass}. |
| 4237 | Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} |
| 4238 | syntax: |
| 4239 | |
| 4240 | @example |
| 4241 | ((inclass 58) (topmost-intro 60)) |
| 4242 | @end example |
| 4243 | |
| 4244 | @ssindex member-init-intro |
| 4245 | @ssindex member-init-cont |
| 4246 | Line 7 introduces a C++ member initialization list and as such is given |
| 4247 | @code{member-init-intro} syntax. Note that in this case it is |
| 4248 | @emph{not} assigned @code{inclass} since this is not considered a |
| 4249 | top-level construct. Lines 8 through 10 are all assigned |
| 4250 | @code{member-init-cont} since they continue the member initialization |
| 4251 | list started on line 7. |
| 4252 | |
| 4253 | @cindex in-class inline methods |
| 4254 | @ssindex inline-open |
| 4255 | @ssindex inline-close |
| 4256 | Line 11's analysis is a bit more complicated: |
| 4257 | |
| 4258 | @example |
| 4259 | ((inclass 58) (inline-open)) |
| 4260 | @end example |
| 4261 | |
| 4262 | This line is assigned a syntax of both @code{inline-open} and |
| 4263 | @code{inclass} because it opens an @dfn{in-class} C++ inline method |
| 4264 | definition. This is distinct from, but related to, the C++ notion of an |
| 4265 | inline function in that its definition occurs inside an enclosing class |
| 4266 | definition, which in C++ implies that the function should be inlined. |
| 4267 | However, if the definition of the @code{Bass} constructor appeared |
| 4268 | outside the class definition, the construct would be given the |
| 4269 | @code{defun-open} syntax, even if the keyword @code{inline} appeared |
| 4270 | before the method name, as in: |
| 4271 | |
| 4272 | @example |
| 4273 | 1: class Bass |
| 4274 | 2: : public Guitar, |
| 4275 | 3: public Amplifiable |
| 4276 | 4: @{ |
| 4277 | 5: public: |
| 4278 | 6: Bass(); |
| 4279 | 7: @}; |
| 4280 | 8: |
| 4281 | 9: inline |
| 4282 | 10: Bass::Bass() |
| 4283 | 11: : eString( new BassString( 0.105 )), |
| 4284 | 12: aString( new BassString( 0.085 )), |
| 4285 | 13: dString( new BassString( 0.065 )), |
| 4286 | 14: gString( new BassString( 0.045 )) |
| 4287 | 15: @{ |
| 4288 | 16: eString.tune( 'E' ); |
| 4289 | 17: aString.tune( 'A' ); |
| 4290 | 18: dString.tune( 'D' ); |
| 4291 | 19: gString.tune( 'G' ); |
| 4292 | 20: @} |
| 4293 | @end example |
| 4294 | |
| 4295 | @ssindex friend |
| 4296 | Returning to the previous example, line 16 is given @code{inline-close} |
| 4297 | syntax, while line 12 is given @code{defun-block-open} syntax, and lines |
| 4298 | 13 through 15 are all given @code{statement} syntax. Line 17 is |
| 4299 | interesting in that its syntactic analysis list contains three |
| 4300 | elements: |
| 4301 | |
| 4302 | @example |
| 4303 | ((inclass 58) (topmost-intro 380) (friend)) |
| 4304 | @end example |
| 4305 | |
| 4306 | The @code{friend} and @code{inline-open} syntactic symbols are |
| 4307 | modifiers that do not have anchor positions. |
| 4308 | |
| 4309 | @ssindex template-args-cont |
| 4310 | Template definitions introduce yet another syntactic symbol: |
| 4311 | |
| 4312 | @example |
| 4313 | 1: ThingManager <int, |
| 4314 | 2: Framework::Callback *, |
| 4315 | 3: Mutex> framework_callbacks; |
| 4316 | @end example |
| 4317 | |
| 4318 | Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 |
| 4319 | are both analyzed as @code{template-args-cont} lines. |
| 4320 | |
| 4321 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4322 | @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols |
| 4323 | @comment node-name, next, previous, up |
| 4324 | @subsection Conditional Construct Symbols |
| 4325 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4326 | |
| 4327 | Here is a (totally contrived) example which illustrates how syntax is |
| 4328 | assigned to various conditional constructs: |
| 4329 | |
| 4330 | @example |
| 4331 | 1: void spam( int index ) |
| 4332 | 2: @{ |
| 4333 | 3: for( int i=0; i<index; i++ ) |
| 4334 | 4: @{ |
| 4335 | 5: if( i == 10 ) |
| 4336 | 6: do_something_special(); |
| 4337 | 7: else |
| 4338 | 8: silly_label: |
| 4339 | 9: do_something( i ); |
| 4340 | 10: @} |
| 4341 | 11: do @{ |
| 4342 | 12: another_thing( i-- ); |
| 4343 | 13: @} |
| 4344 | 14: while( i > 0 ); |
| 4345 | 15: @} |
| 4346 | @end example |
| 4347 | |
| 4348 | Only the lines that illustrate new syntactic symbols will be discussed. |
| 4349 | |
| 4350 | @ssindex substatement-open |
| 4351 | @ssindex statement-block-intro |
| 4352 | @ssindex block-close |
| 4353 | Line 4 has a brace which opens a conditional's substatement block. It |
| 4354 | is thus assigned @code{substatement-open} syntax, and since line 5 is |
| 4355 | the first line in the substatement block, it is assigned |
| 4356 | @code{statement-block-intro} syntax. Line 10 contains the brace |
| 4357 | that closes the inner substatement block, and is therefore given the |
| 4358 | syntax @code{block-close}@footnote{@code{block-open} is used only for |
| 4359 | ``free-standing'' blocks, and is somewhat rare (@pxref{Literal |
| 4360 | Symbols} for an example.)}. Line 13 is treated the same way. |
| 4361 | |
| 4362 | @ssindex substatement |
| 4363 | Lines 6 and 9 are also substatements of conditionals, but since they |
| 4364 | don't start blocks they are given @code{substatement} syntax |
| 4365 | instead of @code{substatement-open}. |
| 4366 | |
| 4367 | @ssindex substatement-label |
| 4368 | Line 8 contains a label, which is normally given @code{label} syntax. |
| 4369 | This one is however a bit special since it's between a conditional and |
| 4370 | its substatement. It's analyzed as @code{substatement-label} to let you |
| 4371 | handle this rather odd case differently from normal labels. |
| 4372 | |
| 4373 | @ssindex else-clause |
| 4374 | @ssindex catch-clause |
| 4375 | Line 7 start with an @code{else} that matches the @code{if} statement on |
| 4376 | line 5. It is therefore given the @code{else-clause} syntax and is |
| 4377 | anchored on the matching @code{if}. The @code{try}-@code{catch} |
| 4378 | constructs in C++ and Java are treated this way too, except that |
| 4379 | @code{catch} and (in Java) @code{finally}, are marked with |
| 4380 | @code{catch-clause}. |
| 4381 | |
| 4382 | @ssindex do-while-closure |
| 4383 | The @code{while} construct on line 14 that closes a @code{do} |
| 4384 | conditional is given the special syntax @code{do-while-closure} if it |
| 4385 | appears on a line by itself. Note that if the @code{while} appeared on |
| 4386 | the same line as the preceding close brace, that line would still have |
| 4387 | @code{block-close} syntax. |
| 4388 | |
| 4389 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4390 | @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols |
| 4391 | @comment node-name, next, previous, up |
| 4392 | @subsection Switch Statement Symbols |
| 4393 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4394 | |
| 4395 | Switch statements have their own set of syntactic symbols. Here's an |
| 4396 | example: |
| 4397 | |
| 4398 | @example |
| 4399 | 1: void spam( enum Ingredient i ) |
| 4400 | 2: @{ |
| 4401 | 3: switch( i ) @{ |
| 4402 | 4: case Ham: |
| 4403 | 5: be_a_pig(); |
| 4404 | 6: break; |
| 4405 | 7: case Salt: |
| 4406 | 8: drink_some_water(); |
| 4407 | 9: break; |
| 4408 | 10: default: |
| 4409 | 11: @{ |
| 4410 | 12: what_is_it(); |
| 4411 | 13: break; |
| 4412 | 14: @} |
| 4413 | 15: @} |
| 4414 | 14: @} |
| 4415 | @end example |
| 4416 | |
| 4417 | @ssindex case-label |
| 4418 | @ssindex statement-case-intro |
| 4419 | @ssindex statement-case-open |
| 4420 | Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, |
| 4421 | while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 |
| 4422 | is treated slightly differently since it contains a brace that opens a |
| 4423 | block --- it is given @code{statement-case-open} syntax. |
| 4424 | |
| 4425 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4426 | @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols |
| 4427 | @comment node-name, next, previous, up |
| 4428 | @subsection Brace List Symbols |
| 4429 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4430 | |
| 4431 | @cindex brace lists |
| 4432 | There are a set of syntactic symbols that are used to recognize |
| 4433 | constructs inside of brace lists. A brace list is defined as an |
| 4434 | @code{enum} or aggregate initializer list, such as might statically |
| 4435 | initialize an array of structs. The three special aggregate constructs |
| 4436 | in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as |
| 4437 | brace lists too. An example: |
| 4438 | |
| 4439 | @example |
| 4440 | 1: static char* ingredients[] = |
| 4441 | 2: @{ |
| 4442 | 3: "Ham", |
| 4443 | 4: "Salt", |
| 4444 | 5: NULL |
| 4445 | 6: @}; |
| 4446 | @end example |
| 4447 | |
| 4448 | @ssindex brace-list-open |
| 4449 | @ssindex brace-list-intro |
| 4450 | @ssindex brace-list-close |
| 4451 | @ssindex brace-list-entry |
| 4452 | Following convention, line 2 in this example is assigned |
| 4453 | @code{brace-list-open} syntax, and line 3 is assigned |
| 4454 | @code{brace-list-intro} syntax. Likewise, line 6 is assigned |
| 4455 | @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned |
| 4456 | @code{brace-list-entry} syntax, as would all subsequent lines in this |
| 4457 | initializer list. |
| 4458 | |
| 4459 | @ssindex brace-entry-open |
| 4460 | Your static initializer might be initializing nested structures, for |
| 4461 | example: |
| 4462 | |
| 4463 | @example |
| 4464 | 1: struct intpairs[] = |
| 4465 | 2: @{ |
| 4466 | 3: @{ 1, 2 @}, |
| 4467 | 4: @{ |
| 4468 | 5: 3, |
| 4469 | 6: 4 |
| 4470 | 7: @} |
| 4471 | 8: @{ 1, |
| 4472 | 9: 2 @}, |
| 4473 | 10: @{ 3, 4 @} |
| 4474 | 11: @}; |
| 4475 | @end example |
| 4476 | |
| 4477 | Here, you've already seen the analysis of lines 1, 2, 3, and 11. On |
| 4478 | line 4, things get interesting; this line is assigned |
| 4479 | @code{brace-entry-open} syntactic symbol because it's a bracelist entry |
| 4480 | line that starts with an open brace. Lines 5 and 6 (and line 9) are |
| 4481 | pretty standard, and line 7 is a @code{brace-list-close} as you'd |
| 4482 | expect. Once again, line 8 is assigned as @code{brace-entry-open} as is |
| 4483 | line 10. |
| 4484 | |
| 4485 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4486 | @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols |
| 4487 | @comment node-name, next, previous, up |
| 4488 | @subsection External Scope Symbols |
| 4489 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4490 | |
| 4491 | External language definition blocks also have their own syntactic |
| 4492 | symbols. In this example: |
| 4493 | |
| 4494 | @example |
| 4495 | 1: extern "C" |
| 4496 | 2: @{ |
| 4497 | 3: int thing_one( int ); |
| 4498 | 4: int thing_two( double ); |
| 4499 | 5: @} |
| 4500 | @end example |
| 4501 | |
| 4502 | @ssindex extern-lang-open |
| 4503 | @ssindex extern-lang-close |
| 4504 | @ssindex inextern-lang |
| 4505 | @ssindex inclass |
| 4506 | @noindent |
| 4507 | line 2 is given the @code{extern-lang-open} syntax, while line 5 is given |
| 4508 | the @code{extern-lang-close} syntax. The analysis for line 3 yields: |
| 4509 | |
| 4510 | @example |
| 4511 | ((inextern-lang) (topmost-intro 14)) |
| 4512 | @end example |
| 4513 | |
| 4514 | @noindent |
| 4515 | where @code{inextern-lang} is a modifier similar in purpose to |
| 4516 | @code{inclass}. |
| 4517 | |
| 4518 | There are various other top level blocks like @code{extern}, and they |
| 4519 | are all treated in the same way except that the symbols are named after |
| 4520 | the keyword that introduces the block. E.g. C++ namespace blocks get |
| 4521 | the three symbols @code{namespace-open}, @code{namespace-close} and |
| 4522 | @code{innamespace}. The currently recognized top level blocks are: |
| 4523 | |
| 4524 | @table @asis |
| 4525 | @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} |
| 4526 | @code{extern} blocks in C and C++.@footnote{These should logically be |
| 4527 | named @code{extern-open}, @code{extern-close} and @code{inextern}, but |
| 4528 | that isn't the case for historical reasons.} |
| 4529 | |
| 4530 | @item @code{namespace-open}, @code{namespace-close}, @code{innamespace} |
| 4531 | @ssindex namespace-open |
| 4532 | @ssindex namespace-close |
| 4533 | @ssindex innamespace |
| 4534 | @code{namespace} blocks in C++. |
| 4535 | |
| 4536 | @item @code{module-open}, @code{module-close}, @code{inmodule} |
| 4537 | @ssindex module-open |
| 4538 | @ssindex module-close |
| 4539 | @ssindex inmodule |
| 4540 | @code{module} blocks in CORBA IDL. |
| 4541 | |
| 4542 | @item @code{composition-open}, @code{composition-close}, @code{incomposition} |
| 4543 | @ssindex composition-open |
| 4544 | @ssindex composition-close |
| 4545 | @ssindex incomposition |
| 4546 | @code{composition} blocks in CORBA CIDL. |
| 4547 | @end table |
| 4548 | |
| 4549 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4550 | @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols |
| 4551 | @comment node-name, next, previous, up |
| 4552 | @subsection Parenthesis (Argument) List Symbols |
| 4553 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4554 | |
| 4555 | A number of syntactic symbols are associated with parenthesis lists, |
| 4556 | a.k.a argument lists, as found in function declarations and function |
| 4557 | calls. This example illustrates these: |
| 4558 | |
| 4559 | @example |
| 4560 | 1: void a_function( int line1, |
| 4561 | 2: int line2 ); |
| 4562 | 3: |
| 4563 | 4: void a_longer_function( |
| 4564 | 5: int line1, |
| 4565 | 6: int line2 |
| 4566 | 7: ); |
| 4567 | 8: |
| 4568 | 9: void call_them( int line1, int line2 ) |
| 4569 | 10: @{ |
| 4570 | 11: a_function( |
| 4571 | 12: line1, |
| 4572 | 13: line2 |
| 4573 | 14: ); |
| 4574 | 15: |
| 4575 | 16: a_longer_function( line1, |
| 4576 | 17: line2 ); |
| 4577 | 18: @} |
| 4578 | @end example |
| 4579 | |
| 4580 | @ssindex arglist-intro |
| 4581 | @ssindex arglist-close |
| 4582 | Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are |
| 4583 | the first line following the open parenthesis, and lines 7 and 14 are |
| 4584 | assigned @code{arglist-close} syntax since they contain the parenthesis |
| 4585 | that closes the argument list. |
| 4586 | |
| 4587 | @ssindex arglist-cont-nonempty |
| 4588 | @ssindex arglist-cont |
| 4589 | Lines that continue argument lists can be assigned one of two syntactic |
| 4590 | symbols. For example, Lines 2 and 17 |
| 4591 | are assigned @code{arglist-cont-nonempty} syntax. What this means |
| 4592 | is that they continue an argument list, but that the line containing the |
| 4593 | parenthesis that opens the list is @emph{not empty} following the open |
| 4594 | parenthesis. Contrast this against lines 6 and 13 which are assigned |
| 4595 | @code{arglist-cont} syntax. This is because the parenthesis that opens |
| 4596 | their argument lists is the last character on that line. |
| 4597 | |
| 4598 | Syntactic elements with @code{arglist-intro}, |
| 4599 | @code{arglist-cont-nonempty}, and @code{arglist-close} contain two |
| 4600 | buffer positions: the anchor position (the beginning of the |
| 4601 | declaration or statement) and the position of the open parenthesis. |
| 4602 | The latter position can be used in a line-up function (@pxref{Line-Up |
| 4603 | Functions}). |
| 4604 | |
| 4605 | Note that there is no @code{arglist-open} syntax. This is because any |
| 4606 | parenthesis that opens an argument list, appearing on a separate line, |
| 4607 | is assigned the @code{statement-cont} syntax instead. |
| 4608 | |
| 4609 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4610 | @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols |
| 4611 | @comment node-name, next, previous, up |
| 4612 | @subsection Comment String Label and Macro Symbols |
| 4613 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4614 | |
| 4615 | A few miscellaneous syntactic symbols that haven't been previously |
| 4616 | covered are illustrated by this C++ example: |
| 4617 | |
| 4618 | @example |
| 4619 | 1: void Bass::play( int volume ) |
| 4620 | 2: const |
| 4621 | 3: @{ |
| 4622 | 4: /* this line starts a multiline |
| 4623 | 5: * comment. This line should get `c' syntax */ |
| 4624 | 6: |
| 4625 | 7: char* a_multiline_string = "This line starts a multiline \ |
| 4626 | 8: string. This line should get `string' syntax."; |
| 4627 | 9: |
| 4628 | 10: note: |
| 4629 | 11: @{ |
| 4630 | 12: #ifdef LOCK |
| 4631 | 13: Lock acquire(); |
| 4632 | 14: #endif // LOCK |
| 4633 | 15: slap_pop(); |
| 4634 | 16: cout << "I played " |
| 4635 | 17: << "a note\n"; |
| 4636 | 18: @} |
| 4637 | 19: @} |
| 4638 | @end example |
| 4639 | |
| 4640 | The lines to note in this example include: |
| 4641 | |
| 4642 | @itemize @bullet |
| 4643 | @item |
| 4644 | @ssindex func-decl-cont |
| 4645 | Line 2 is assigned the @code{func-decl-cont} syntax. |
| 4646 | |
| 4647 | @item |
| 4648 | @ssindex comment-intro |
| 4649 | Line 4 is assigned both @code{defun-block-intro} @emph{and} |
| 4650 | @code{comment-intro} syntax. A syntactic element with |
| 4651 | @code{comment-intro} has no anchor point --- It is always accompanied |
| 4652 | by another syntactic element which does have one. |
| 4653 | |
| 4654 | @item |
| 4655 | @ssindex c |
| 4656 | Line 5 is assigned @code{c} syntax. |
| 4657 | |
| 4658 | @item |
| 4659 | @cindex syntactic whitespace |
| 4660 | Line 6 which, even though it contains nothing but whitespace, is |
| 4661 | assigned @code{defun-block-intro}. Note that the appearance of the |
| 4662 | comment on lines 4 and 5 do not cause line 6 to be assigned |
| 4663 | @code{statement} syntax because comments are considered to be |
| 4664 | @dfn{syntactic whitespace}, which are ignored when analyzing |
| 4665 | code. |
| 4666 | |
| 4667 | @item |
| 4668 | @ssindex string |
| 4669 | Line 8 is assigned @code{string} syntax. |
| 4670 | |
| 4671 | @item |
| 4672 | @ssindex label |
| 4673 | Line 10 is assigned @code{label} syntax. |
| 4674 | |
| 4675 | @item |
| 4676 | @ssindex block-open |
| 4677 | Line 11 is assigned @code{block-open} as well as @code{statement} |
| 4678 | syntax. A @code{block-open} syntactic element doesn't have an anchor |
| 4679 | position, since it always appears with another syntactic element which |
| 4680 | does have one. |
| 4681 | |
| 4682 | @item |
| 4683 | @ssindex cpp-macro |
| 4684 | Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the |
| 4685 | normal syntactic symbols (@code{statement-block-intro} and |
| 4686 | @code{statement}, respectively). Normally @code{cpp-macro} is |
| 4687 | configured to cancel out the normal syntactic context to make all |
| 4688 | preprocessor directives stick to the first column, but that's easily |
| 4689 | changed if you want preprocessor directives to be indented like the rest |
| 4690 | of the code. Like @code{comment-intro}, a syntactic element with |
| 4691 | @code{cpp-macro} doesn't contain an anchor position. |
| 4692 | |
| 4693 | @item |
| 4694 | @ssindex stream-op |
| 4695 | Line 17 is assigned @code{stream-op} syntax. |
| 4696 | @end itemize |
| 4697 | |
| 4698 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4699 | @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols |
| 4700 | @comment node-name, next, previous, up |
| 4701 | @subsection Multiline Macro Symbols |
| 4702 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4703 | |
| 4704 | @cindex multiline macros |
| 4705 | @cindex syntactic whitespace |
| 4706 | @ssindex cpp-define-intro |
| 4707 | @ssindex cpp-macro-cont |
| 4708 | Multiline preprocessor macro definitions are normally handled just like |
| 4709 | other code, i.e. the lines inside them are indented according to the |
| 4710 | syntactic analysis of the preceding lines inside the macro. The first |
| 4711 | line inside a macro definition (i.e. the line after the starting line of |
| 4712 | the cpp directive itself) gets @code{cpp-define-intro}. In this example: |
| 4713 | |
| 4714 | @example |
| 4715 | 1: #define LIST_LOOP(cons, listp) \ |
| 4716 | 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ |
| 4717 | 3: if (!CONSP (cons)) \ |
| 4718 | 4: signal_error ("Invalid list format", listp); \ |
| 4719 | 5: else |
| 4720 | @end example |
| 4721 | |
| 4722 | @noindent |
| 4723 | line 1 is given the syntactic symbol @code{cpp-macro}. The first line |
| 4724 | of a cpp directive is always given that symbol. Line 2 is given |
| 4725 | @code{cpp-define-intro}, so that you can give the macro body as a whole |
| 4726 | some extra indentation. Lines 3 through 5 are then analyzed as normal |
| 4727 | code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} |
| 4728 | on line 5. |
| 4729 | |
| 4730 | The syntactic analysis inside macros can be turned off with |
| 4731 | @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In |
| 4732 | that case, lines 2 through 5 would all be given @code{cpp-macro-cont} |
| 4733 | with an anchor position pointing to the @code{#} which starts the cpp |
| 4734 | directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed |
| 4735 | macros.}. |
| 4736 | |
| 4737 | @xref{Custom Macros}, for more info about the treatment of macros. |
| 4738 | |
| 4739 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4740 | @node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols |
| 4741 | @comment node-name, next, previous, up |
| 4742 | @subsection Objective-C Method Symbols |
| 4743 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4744 | |
| 4745 | In Objective-C buffers, there are three additional syntactic symbols |
| 4746 | assigned to various message calling constructs. Here's an example |
| 4747 | illustrating these: |
| 4748 | |
| 4749 | @example |
| 4750 | 1: - (void)setDelegate:anObject |
| 4751 | 2: withStuff:stuff |
| 4752 | 3: @{ |
| 4753 | 4: [delegate masterWillRebind:self |
| 4754 | 5: toDelegate:anObject |
| 4755 | 6: withExtraStuff:stuff]; |
| 4756 | 7: @} |
| 4757 | @end example |
| 4758 | |
| 4759 | @ssindex objc-method-intro |
| 4760 | @ssindex objc-method-args-cont |
| 4761 | @ssindex objc-method-call-cont |
| 4762 | Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is |
| 4763 | assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both |
| 4764 | assigned @code{objc-method-call-cont} syntax. |
| 4765 | |
| 4766 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4767 | @node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols |
| 4768 | @comment node-name, next, previous, up |
| 4769 | @subsection Anonymous Class Symbol (Java) |
| 4770 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4771 | |
| 4772 | Java has a concept of anonymous classes which can look something like |
| 4773 | this: |
| 4774 | |
| 4775 | @example |
| 4776 | 1: public void watch(Observable o) @{ |
| 4777 | 2: o.addObserver(new Observer() @{ |
| 4778 | 3: public void update(Observable o, Object arg) @{ |
| 4779 | 4: history.addElement(arg); |
| 4780 | 5: @} |
| 4781 | 6: @}); |
| 4782 | 7: @} |
| 4783 | @end example |
| 4784 | |
| 4785 | @ssindex inexpr-class |
| 4786 | The brace following the @code{new} operator opens the anonymous class. |
| 4787 | Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the |
| 4788 | @code{inclass} symbol used in normal classes. Thus, the class will be |
| 4789 | indented just like a normal class, with the added indentation given to |
| 4790 | @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't |
| 4791 | have an anchor position. |
| 4792 | |
| 4793 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4794 | @node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols |
| 4795 | @comment node-name, next, previous, up |
| 4796 | @subsection Statement Block Symbols |
| 4797 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4798 | |
| 4799 | There are a few occasions where a statement block might be used inside |
| 4800 | an expression. One is in C or C++ code using the gcc extension for |
| 4801 | this, e.g: |
| 4802 | |
| 4803 | @example |
| 4804 | 1: int res = (@{ |
| 4805 | 2: int y = foo (); int z; |
| 4806 | 3: if (y > 0) z = y; else z = - y; |
| 4807 | 4: z; |
| 4808 | 5: @}); |
| 4809 | @end example |
| 4810 | |
| 4811 | @ssindex inexpr-statement |
| 4812 | Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the |
| 4813 | symbols they'd get in a normal block. Therefore, the indentation put on |
| 4814 | @code{inexpr-statement} is added to the normal statement block |
| 4815 | indentation. An @code{inexpr-statement} syntactic element doesn't |
| 4816 | contain an anchor position. |
| 4817 | |
| 4818 | In Pike code, there are a few other situations where blocks occur inside |
| 4819 | statements, as illustrated here: |
| 4820 | |
| 4821 | @example |
| 4822 | 1: array itgob() |
| 4823 | 2: @{ |
| 4824 | 3: string s = map (backtrace()[-2][3..], |
| 4825 | 4: lambda |
| 4826 | 5: (mixed arg) |
| 4827 | 6: @{ |
| 4828 | 7: return sprintf ("%t", arg); |
| 4829 | 8: @}) * ", " + "\n"; |
| 4830 | 9: return catch @{ |
| 4831 | 10: write (s + "\n"); |
| 4832 | 11: @}; |
| 4833 | 12: @} |
| 4834 | @end example |
| 4835 | |
| 4836 | @ssindex inlambda |
| 4837 | @ssindex lambda-intro-cont |
| 4838 | Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes |
| 4839 | by the @code{lambda} keyword. If the function argument list is put |
| 4840 | on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} |
| 4841 | syntax. The function body is handled as an inline method body, with the |
| 4842 | addition of the @code{inlambda} syntactic symbol. This means that line |
| 4843 | 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets |
| 4844 | @code{inline-close}@footnote{You might wonder why it doesn't get |
| 4845 | @code{inlambda} too. It's because the closing brace is relative to the |
| 4846 | opening brace, which stands on its own line in this example. If the |
| 4847 | opening brace was hanging on the previous line, then the closing brace |
| 4848 | would get the @code{inlambda} syntax too to be indented correctly.}. |
| 4849 | |
| 4850 | @ssindex inexpr-statement |
| 4851 | On line 9, @code{catch} is a special function taking a statement block |
| 4852 | as its argument. The block is handled as an in-expression statement |
| 4853 | with the @code{inexpr-statement} syntax, just like the gcc extended C |
| 4854 | example above. The other similar special function, @code{gauge}, is |
| 4855 | handled like this too. |
| 4856 | |
| 4857 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4858 | @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols |
| 4859 | @comment node-name, next, previous, up |
| 4860 | @subsection K&R Symbols |
| 4861 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4862 | |
| 4863 | @ssindex knr-argdecl-intro |
| 4864 | @ssindex knr-argdecl |
| 4865 | Two other syntactic symbols can appear in old style, non-prototyped C |
| 4866 | code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: |
| 4867 | |
| 4868 | @example |
| 4869 | 1: int add_three_integers(a, b, c) |
| 4870 | 2: int a; |
| 4871 | 3: int b; |
| 4872 | 4: int c; |
| 4873 | 5: @{ |
| 4874 | 6: return a + b + c; |
| 4875 | 7: @} |
| 4876 | @end example |
| 4877 | |
| 4878 | Here, line 2 is the first line in an argument declaration list and so is |
| 4879 | given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines |
| 4880 | (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} |
| 4881 | syntax. |
| 4882 | |
| 4883 | |
| 4884 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4885 | @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics |
| 4886 | @comment node-name, next, previous, up |
| 4887 | @section Indentation Calculation |
| 4888 | @cindex indentation |
| 4889 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4890 | |
| 4891 | Indentation for a line is calculated from the syntactic context |
| 4892 | (@pxref{Syntactic Analysis}). |
| 4893 | |
| 4894 | First, a buffer position is found whose column will be the base for the |
| 4895 | indentation calculation. It's the anchor position in the first |
| 4896 | syntactic element that provides one that is used. If no syntactic |
| 4897 | element has an anchor position then column zero is used. |
| 4898 | |
| 4899 | Second, the syntactic symbols in each syntactic element are looked up |
| 4900 | in the @code{c-offsets-alist} style variable |
| 4901 | (@pxref{c-offsets-alist}), which is an association list of syntactic |
| 4902 | symbols and the offsets to apply for those symbols. These offsets are |
| 4903 | added together with the base column to produce the new indentation |
| 4904 | column. |
| 4905 | |
| 4906 | Let's use our two code examples above to see how this works. Here is |
| 4907 | our first example again: |
| 4908 | |
| 4909 | @example |
| 4910 | 1: void swap( int& a, int& b ) |
| 4911 | 2: @{ |
| 4912 | 3: int tmp = a; |
| 4913 | 4: a = b; |
| 4914 | 5: b = tmp; |
| 4915 | 6: @} |
| 4916 | @end example |
| 4917 | |
| 4918 | Let's say point is on line 3 and we hit the @key{TAB} key to reindent |
| 4919 | the line. The syntactic context for that line is: |
| 4920 | |
| 4921 | @example |
| 4922 | ((defun-block-intro 29)) |
| 4923 | @end example |
| 4924 | |
| 4925 | @noindent |
| 4926 | Since buffer position 29 is the first and only anchor position in the |
| 4927 | list, @ccmode{} goes there and asks for the current column. This brace |
| 4928 | is in column zero, so @ccmode{} uses @samp{0} as the base column. |
| 4929 | |
| 4930 | Next, @ccmode{} looks up @code{defun-block-intro} in the |
| 4931 | @code{c-offsets-alist} style variable. Let's say it finds the value |
| 4932 | @samp{4}; it adds this to the base column @samp{0}, yielding a running |
| 4933 | total indentation of 4 spaces. |
| 4934 | |
| 4935 | Since there is only one syntactic element on the list for this line, |
| 4936 | indentation calculation is complete, and the total indentation for the |
| 4937 | line is 4 spaces. |
| 4938 | |
| 4939 | Here's another example: |
| 4940 | |
| 4941 | @example |
| 4942 | 1: int add( int val, int incr, int doit ) |
| 4943 | 2: @{ |
| 4944 | 3: if( doit ) |
| 4945 | 4: @{ |
| 4946 | 5: return( val + incr ); |
| 4947 | 6: @} |
| 4948 | 7: return( val ); |
| 4949 | 8: @} |
| 4950 | @end example |
| 4951 | |
| 4952 | If we were to hit @kbd{TAB} on line 4 in the above example, the same |
| 4953 | basic process is performed, despite the differences in the syntactic |
| 4954 | context. The context for this line is: |
| 4955 | |
| 4956 | @example |
| 4957 | ((substatement-open 46)) |
| 4958 | @end example |
| 4959 | |
| 4960 | Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in |
| 4961 | @code{if} on line 3. This character is in the fourth column on that |
| 4962 | line so the base column is @samp{4}. Then @ccmode{} looks up the |
| 4963 | @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it |
| 4964 | finds the value @samp{4}. It's added with the base column and yields an |
| 4965 | indentation for the line of 8 spaces. |
| 4966 | |
| 4967 | Simple, huh? |
| 4968 | |
| 4969 | Actually, it's a bit more complicated than that since the entries on |
| 4970 | @code{c-offsets-alist} can be much more than plain offsets. |
| 4971 | @xref{c-offsets-alist}, for the full story. |
| 4972 | |
| 4973 | Anyway, the mode usually just does The Right Thing without you having to |
| 4974 | think about it in this much detail. But when customizing indentation, |
| 4975 | it's helpful to understand the general indentation model being used. |
| 4976 | |
| 4977 | As you configure @ccmode{}, you might want to set the variable |
| 4978 | @code{c-echo-syntactic-information-p} to non-@code{nil} so that the |
| 4979 | syntactic context and calculated offset always is echoed in the |
| 4980 | minibuffer when you hit @kbd{TAB}. |
| 4981 | |
| 4982 | |
| 4983 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4984 | @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top |
| 4985 | @comment node-name, next, previous, up |
| 4986 | @chapter Customizing Indentation |
| 4987 | @cindex customization, indentation |
| 4988 | @cindex indentation |
| 4989 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 4990 | |
| 4991 | The principal variable for customizing indentation is the style |
| 4992 | variable @code{c-offsets-alist}, which gives an @dfn{offset} (an |
| 4993 | indentation rule) for each syntactic symbol. Its structure and |
| 4994 | semantics are completely described in @ref{c-offsets-alist}. The |
| 4995 | various ways you can set the variable, including the use of the |
| 4996 | @ccmode{} style system, are described in @ref{Config Basics} and its |
| 4997 | sections, in particular @ref{Style Variables}. |
| 4998 | |
| 4999 | The simplest and most used kind of ``offset'' setting in |
| 5000 | @code{c-offsets-alist} is in terms of multiples of |
| 5001 | @code{c-basic-offset}: |
| 5002 | |
| 5003 | @defopt c-basic-offset |
| 5004 | @vindex basic-offset (c-) |
| 5005 | This style variable holds the basic offset between indentation levels. |
| 5006 | It's factory default is 4, but all the built-in styles set it |
| 5007 | themselves, to some value between 2 (for @code{gnu} style) and 8 (for |
| 5008 | @code{bsd}, @code{linux}, and @code{python} styles). |
| 5009 | @end defopt |
| 5010 | |
| 5011 | The most flexible ``offset'' setting you can make in |
| 5012 | @code{c-offsets-alist} is a line-up function (or even a list of them), |
| 5013 | either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one |
| 5014 | you write yourself (@pxref{Custom Line-Up}). |
| 5015 | |
| 5016 | Finally, in @ref{Other Indentation} you'll find the tool of last |
| 5017 | resort: a hook which is called after a line has been indented. You |
| 5018 | can install functions here to make ad-hoc adjustments to any line's |
| 5019 | indentation. |
| 5020 | |
| 5021 | @menu |
| 5022 | * c-offsets-alist:: |
| 5023 | * Interactive Customization:: |
| 5024 | * Line-Up Functions:: |
| 5025 | * Custom Line-Up:: |
| 5026 | * Other Indentation:: |
| 5027 | @end menu |
| 5028 | |
| 5029 | |
| 5030 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5031 | @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation |
| 5032 | @comment node-name, next, previous, up |
| 5033 | @section c-offsets-alist |
| 5034 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5035 | |
| 5036 | This section explains the structure and semantics of the style |
| 5037 | variable @code{c-offset-alist}, the principal variable for configuring |
| 5038 | indentation. Details of how to set it up, and its relationship to |
| 5039 | @ccmode{}'s style system are given in @ref{Style Variables}. |
| 5040 | |
| 5041 | @defopt c-offsets-alist |
| 5042 | @vindex offsets-alist (c-) |
| 5043 | This is an alist which associates an offset with each syntactic |
| 5044 | symbol. This @dfn{offset} is a rule specifying how to indent a line |
| 5045 | whose syntactic context matches the symbol. @xref{Syntactic |
| 5046 | Analysis}. |
| 5047 | |
| 5048 | Note that the buffer-local binding of this alist in a @ccmode{} buffer |
| 5049 | contains an entry for @emph{every} syntactic symbol. Its global |
| 5050 | binding and its settings within style specifications usually contain |
| 5051 | only a few entries. @xref{Style Variables}. |
| 5052 | |
| 5053 | The offset specification associated with any particular syntactic |
| 5054 | symbol can be an integer, a variable name, a vector, a function or |
| 5055 | lambda expression, a list, or one of the following special symbols: |
| 5056 | @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The |
| 5057 | meanings of these values are described in detail below. |
| 5058 | |
| 5059 | Here is an example fragment of a @code{c-offsets-alist}, showing some |
| 5060 | of these kinds of offsets: |
| 5061 | |
| 5062 | @example |
| 5063 | ((statement . 0) |
| 5064 | (substatement . +) |
| 5065 | (cpp-macro . [0]) |
| 5066 | (topmost-intro-cont . c-lineup-topmost-intro-cont) |
| 5067 | (statement-block-intro . (add c-lineup-whitesmith-in-block |
| 5068 | c-indent-multi-line-block)) |
| 5069 | @dots{} |
| 5070 | @*) |
| 5071 | @end example |
| 5072 | @end defopt |
| 5073 | |
| 5074 | @deffn Command c-set-offset (@kbd{C-c C-o}) |
| 5075 | @findex set-offset (c-) |
| 5076 | @kindex C-c C-o |
| 5077 | This command changes the entry for a syntactic symbol in the current |
| 5078 | binding of @code{c-offsets-alist}, or it inserts a new entry if there |
| 5079 | isn't already one for that syntactic symbol. |
| 5080 | |
| 5081 | You can use @code{c-set-offsets} interactively within a @ccmode{} |
| 5082 | buffer to make experimental changes to your indentation settings. |
| 5083 | @kbd{C-c C-o} prompts you for the syntactic symbol to change |
| 5084 | (defaulting to that of the current line) and the new offset |
| 5085 | (defaulting to the current offset). |
| 5086 | |
| 5087 | @code{c-set-offsets} takes two arguments when used programmatically: |
| 5088 | @var{symbol}, the syntactic element symbol to change and @var{offset}, |
| 5089 | the new offset for that syntactic element. You can call the command |
| 5090 | in your @file{.emacs} to change the global binding of |
| 5091 | @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a |
| 5092 | hook function to make changes from the current style. @ccmode{} |
| 5093 | itself uses this function when initializing styles. |
| 5094 | @end deffn |
| 5095 | |
| 5096 | @cindex offset specification |
| 5097 | The ``offset specifications'' in @code{c-offsets-alist} can be any of |
| 5098 | the following: |
| 5099 | |
| 5100 | @table @asis |
| 5101 | @item An integer |
| 5102 | The integer specifies a relative offset. All relative |
| 5103 | offsets@footnote{The syntactic context @code{@w{((defun-block-intro |
| 5104 | 2724) (comment-intro))}} would likely have two relative offsets.} will |
| 5105 | be added together and used to calculate the indentation relative to an |
| 5106 | anchor position earlier in the buffer. @xref{Indentation |
| 5107 | Calculation}, for details. Most of the time, it's probably better to |
| 5108 | use one of the special symbols like @code{+} than an integer (apart |
| 5109 | from zero). |
| 5110 | |
| 5111 | @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} |
| 5112 | These special symbols describe a relative offset in multiples of |
| 5113 | @code{c-basic-offset}: |
| 5114 | |
| 5115 | By defining a style's indentation in terms of @code{c-basic-offset}, |
| 5116 | you can change the amount of whitespace given to an indentation level |
| 5117 | while maintaining the same basic shape of your code. Here are the |
| 5118 | values that the special symbols correspond to: |
| 5119 | |
| 5120 | @table @code |
| 5121 | @item + |
| 5122 | @code{c-basic-offset} times 1 |
| 5123 | @item - |
| 5124 | @code{c-basic-offset} times -1 |
| 5125 | @item ++ |
| 5126 | @code{c-basic-offset} times 2 |
| 5127 | @item -- |
| 5128 | @code{c-basic-offset} times -2 |
| 5129 | @item * |
| 5130 | @code{c-basic-offset} times 0.5 |
| 5131 | @item / |
| 5132 | @code{c-basic-offset} times -0.5 |
| 5133 | @end table |
| 5134 | |
| 5135 | @item A vector |
| 5136 | The first element of the vector, an integer, sets the absolute |
| 5137 | indentation column. This will override any previously calculated |
| 5138 | indentation, but won't override relative indentation calculated from |
| 5139 | syntactic elements later on in the syntactic context of the line being |
| 5140 | indented. @xref{Indentation Calculation}. Any elements in the vector |
| 5141 | beyond the first will be ignored. |
| 5142 | |
| 5143 | @item A function or lambda expression |
| 5144 | The function will be called and its return value will in turn be |
| 5145 | evaluated as an offset specification. Functions are useful when more |
| 5146 | context than just the syntactic symbol is needed to get the desired |
| 5147 | indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for |
| 5148 | details about them. |
| 5149 | |
| 5150 | @item A symbol with a variable binding |
| 5151 | If the symbol also has a function binding, the function takes |
| 5152 | precedence over the variable. Otherwise the value of the variable is |
| 5153 | used. It must be an integer (which is used as relative offset) or a |
| 5154 | vector (an absolute offset). |
| 5155 | |
| 5156 | @item A list |
| 5157 | The offset can also be a list containing several offset |
| 5158 | specifications; these are evaluated recursively and combined. A list |
| 5159 | is typically only useful when some of the offsets are line-up |
| 5160 | functions. A common strategy is calling a sequence of functions in |
| 5161 | turn until one of them recognizes that it is appropriate for the |
| 5162 | source line and returns a non-@code{nil} value. |
| 5163 | |
| 5164 | @code{nil} values are always ignored when the offsets are combined. |
| 5165 | The first element of the list specifies the method of combining the |
| 5166 | non-@code{nil} offsets from the remaining elements: |
| 5167 | |
| 5168 | @table @code |
| 5169 | @item first |
| 5170 | Use the first offset that doesn't evaluate to @code{nil}. Subsequent |
| 5171 | elements of the list don't get evaluated. |
| 5172 | @item min |
| 5173 | Use the minimum of all the offsets. All must be either relative or |
| 5174 | absolute - they can't be mixed. |
| 5175 | @item max |
| 5176 | Use the maximum of all the offsets. All must be either relative or |
| 5177 | absolute - they can't be mixed. |
| 5178 | @item add |
| 5179 | Add all the evaluated offsets together. Exactly one of them may be |
| 5180 | absolute, in which case the result is absolute. Any relative offsets |
| 5181 | that preceded the absolute one in the list will be ignored in that case. |
| 5182 | @end table |
| 5183 | |
| 5184 | As a compatibility measure, if the first element is none of the above |
| 5185 | then it too will be taken as an offset specification and the whole list |
| 5186 | will be combined according to the method @code{first}. |
| 5187 | @end table |
| 5188 | |
| 5189 | @vindex c-strict-syntax-p |
| 5190 | @vindex strict-syntax-p (c-) |
| 5191 | If an offset specification evaluates to @code{nil}, then a relative |
| 5192 | offset of 0 (zero) is used@footnote{There is however a variable |
| 5193 | @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an |
| 5194 | error to be signaled in that case. It's now considered obsolete since |
| 5195 | it doesn't work well with some of the alignment functions that return |
| 5196 | @code{nil} instead of zero. You should therefore leave |
| 5197 | @code{c-strict-syntax-p} set to @code{nil}.}. |
| 5198 | |
| 5199 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5200 | @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation |
| 5201 | @comment node-name, next, previous, up |
| 5202 | @section Interactive Customization |
| 5203 | @cindex customization, interactive |
| 5204 | @cindex interactive customization |
| 5205 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5206 | |
| 5207 | As an example of how to customize indentation, let's change the |
| 5208 | style of this example@footnote{In this and subsequent examples, the |
| 5209 | original code is formatted using the @samp{gnu} style unless otherwise |
| 5210 | indicated. @xref{Styles}.}: |
| 5211 | |
| 5212 | @example |
| 5213 | @group |
| 5214 | 1: int add( int val, int incr, int doit ) |
| 5215 | 2: @{ |
| 5216 | 3: if( doit ) |
| 5217 | 4: @{ |
| 5218 | 5: return( val + incr ); |
| 5219 | 6: @} |
| 5220 | 7: return( val ); |
| 5221 | 8: @} |
| 5222 | @end group |
| 5223 | @end example |
| 5224 | |
| 5225 | @noindent |
| 5226 | to: |
| 5227 | |
| 5228 | @example |
| 5229 | @group |
| 5230 | 1: int add( int val, int incr, int doit ) |
| 5231 | 2: @{ |
| 5232 | 3: if( doit ) |
| 5233 | 4: @{ |
| 5234 | 5: return( val + incr ); |
| 5235 | 6: @} |
| 5236 | 7: return( val ); |
| 5237 | 8: @} |
| 5238 | @end group |
| 5239 | @end example |
| 5240 | |
| 5241 | In other words, we want to change the indentation of braces that open a |
| 5242 | block following a condition so that the braces line up under the |
| 5243 | conditional, instead of being indented. Notice that the construct we |
| 5244 | want to change starts on line 4. To change the indentation of a line, |
| 5245 | we need to see which syntactic symbols affect the offset calculations |
| 5246 | for that line. Hitting @kbd{C-c C-s} on line 4 yields: |
| 5247 | |
| 5248 | @example |
| 5249 | ((substatement-open 44)) |
| 5250 | @end example |
| 5251 | |
| 5252 | @noindent |
| 5253 | so we know that to change the offset of the open brace, we need to |
| 5254 | change the indentation for the @code{substatement-open} syntactic |
| 5255 | symbol. |
| 5256 | |
| 5257 | To do this interactively, just hit @kbd{C-c C-o}. This prompts |
| 5258 | you for the syntactic symbol to change, providing a reasonable default. |
| 5259 | In this case, the default is @code{substatement-open}, which is just the |
| 5260 | syntactic symbol we want to change! |
| 5261 | |
| 5262 | After you hit return, @ccmode{} will then prompt you for the new |
| 5263 | offset value, with the old value as the default. The default in this |
| 5264 | case is @samp{+}, but we want no extra indentation so enter |
| 5265 | @samp{0} and @kbd{RET}. This will associate the offset 0 with the |
| 5266 | syntactic symbol @code{substatement-open}. |
| 5267 | |
| 5268 | To check your changes quickly, just hit @kbd{C-c C-q} |
| 5269 | (@code{c-indent-defun}) to reindent the entire function. The example |
| 5270 | should now look like: |
| 5271 | |
| 5272 | @example |
| 5273 | @group |
| 5274 | 1: int add( int val, int incr, int doit ) |
| 5275 | 2: @{ |
| 5276 | 3: if( doit ) |
| 5277 | 4: @{ |
| 5278 | 5: return( val + incr ); |
| 5279 | 6: @} |
| 5280 | 7: return( val ); |
| 5281 | 8: @} |
| 5282 | @end group |
| 5283 | @end example |
| 5284 | |
| 5285 | Notice how just changing the open brace offset on line 4 is all we |
| 5286 | needed to do. Since the other affected lines are indented relative to |
| 5287 | line 4, they are automatically indented the way you'd expect. For more |
| 5288 | complicated examples, this might not always work. The general approach |
| 5289 | to take is to always start adjusting offsets for lines higher up in the |
| 5290 | file, then reindent and see if any following lines need further |
| 5291 | adjustments. |
| 5292 | |
| 5293 | @c Move this bit to "Styles" (2005/10/7) |
| 5294 | @deffn Command c-set-offset symbol offset |
| 5295 | @findex set-offset (c-) |
| 5296 | @kindex C-c C-o |
| 5297 | This is the command bound to @kbd{C-c C-o}. It provides a convenient |
| 5298 | way to set offsets on @code{c-offsets-alist} both interactively (see |
| 5299 | the example above) and from your mode hook. |
| 5300 | |
| 5301 | It takes two arguments when used programmatically: @var{symbol} is the |
| 5302 | syntactic element symbol to change and @var{offset} is the new offset |
| 5303 | for that syntactic element. |
| 5304 | @end deffn |
| 5305 | @c End of MOVE THIS BIT. |
| 5306 | |
| 5307 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5308 | @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation |
| 5309 | @comment node-name, next, previous, up |
| 5310 | @section Line-Up Functions |
| 5311 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5312 | |
| 5313 | @cindex line-up function |
| 5314 | @cindex indentation function |
| 5315 | Often there are cases when a simple offset setting on a syntactic |
| 5316 | symbol isn't enough to get the desired indentation---for example, you |
| 5317 | might want to line up a closing parenthesis with the matching opening |
| 5318 | one rather than indenting relative to its ``anchor point''. @ccmode{} |
| 5319 | provides this flexibility with @dfn{line-up functions}. |
| 5320 | |
| 5321 | The way you associate a line-up function with a syntactic symbol is |
| 5322 | described in @ref{c-offsets-alist}. @ccmode{} comes with many |
| 5323 | predefined line-up functions for common situations. If none of these |
| 5324 | does what you want, you can write your own. @xref{Custom Line-Up}. |
| 5325 | Sometimes, it is easier to tweak the standard indentation by adding a |
| 5326 | function to @code{c-special-indent-hook} (@pxref{Other Indentation}). |
| 5327 | |
| 5328 | The line-up functions haven't been adapted for AWK buffers or tested |
| 5329 | with them. Some of them might work serendipitously. There shouldn't be |
| 5330 | any problems writing custom line-up functions for AWK mode. |
| 5331 | |
| 5332 | The calling convention for line-up functions is described fully in |
| 5333 | @ref{Custom Line-Up}. Roughly speaking, the return value is either an |
| 5334 | offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, |
| 5335 | meaning ``this function is inappropriate in this case - try a |
| 5336 | different one''. @xref{c-offsets-alist}. |
| 5337 | |
| 5338 | The subsections below describe all the standard line-up functions, |
| 5339 | categorized by the sort of token the lining-up centers around. For |
| 5340 | each of these functions there is a ``works with'' list that indicates |
| 5341 | which syntactic symbols the function is intended to be used with. |
| 5342 | |
| 5343 | @macro workswith |
| 5344 | @emph{Works with:@ } |
| 5345 | @end macro |
| 5346 | @ifinfo |
| 5347 | @unmacro workswith |
| 5348 | @macro workswith |
| 5349 | Works with: |
| 5350 | @end macro |
| 5351 | @end ifinfo |
| 5352 | |
| 5353 | @macro sssTBasicOffset |
| 5354 | <--> @i{c-basic-offset}@c |
| 5355 | @end macro |
| 5356 | |
| 5357 | @macro sssTsssTBasicOffset |
| 5358 | <--><--> @i{c-basic-offset}@c |
| 5359 | @end macro |
| 5360 | |
| 5361 | @macro hereFn{func} |
| 5362 | <- @i{\func\}@c |
| 5363 | @end macro |
| 5364 | |
| 5365 | @c The TeX backend seems to insert extra spaces around the argument. :P |
| 5366 | @iftex |
| 5367 | @unmacro hereFn |
| 5368 | @macro hereFn{func} |
| 5369 | <-@i{\func\}@c |
| 5370 | @end macro |
| 5371 | @end iftex |
| 5372 | |
| 5373 | @menu |
| 5374 | * Brace/Paren Line-Up:: |
| 5375 | * List Line-Up:: |
| 5376 | * Operator Line-Up:: |
| 5377 | * Comment Line-Up:: |
| 5378 | * Misc Line-Up:: |
| 5379 | @end menu |
| 5380 | |
| 5381 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5382 | @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions |
| 5383 | @comment node-name, next, previous, up |
| 5384 | @subsection Brace and Parenthesis Line-Up Functions |
| 5385 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5386 | |
| 5387 | The line-up functions here calculate the indentation for braces, |
| 5388 | parentheses and statements within brace blocks. |
| 5389 | |
| 5390 | @defun c-lineup-close-paren |
| 5391 | @findex lineup-close-paren (c-) |
| 5392 | Line up the closing paren under its corresponding open paren if the |
| 5393 | open paren is followed by code. If the open paren ends its line, no |
| 5394 | indentation is added. E.g: |
| 5395 | |
| 5396 | @example |
| 5397 | @group |
| 5398 | main (int, |
| 5399 | char ** |
| 5400 | ) @hereFn{c-lineup-close-paren} |
| 5401 | @end group |
| 5402 | @end example |
| 5403 | |
| 5404 | @noindent |
| 5405 | and |
| 5406 | |
| 5407 | @example |
| 5408 | @group |
| 5409 | main ( |
| 5410 | int, char ** |
| 5411 | ) @hereFn{c-lineup-close-paren} |
| 5412 | @end group |
| 5413 | @end example |
| 5414 | |
| 5415 | As a special case, if a brace block is opened at the same line as the |
| 5416 | open parenthesis of the argument list, the indentation is |
| 5417 | @code{c-basic-offset} instead of the open paren column. See |
| 5418 | @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. |
| 5419 | |
| 5420 | @workswith All @code{*-close} symbols. |
| 5421 | @end defun |
| 5422 | |
| 5423 | @comment ------------------------------------------------------------ |
| 5424 | |
| 5425 | @anchor{c-lineup-arglist-close-under-paren} |
| 5426 | @defun c-lineup-arglist-close-under-paren |
| 5427 | @findex lineup-arglist-close-under-paren (c-) |
| 5428 | Set your @code{arglist-close} syntactic symbol to this line-up function |
| 5429 | so that parentheses that close argument lists will line up under the |
| 5430 | parenthesis that opened the argument list. It can also be used with |
| 5431 | @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all |
| 5432 | lines inside a parenthesis under the open paren. |
| 5433 | |
| 5434 | As a special case, if a brace block is opened at the same line as the |
| 5435 | open parenthesis of the argument list, the indentation is |
| 5436 | @code{c-basic-offset} only. See @code{c-lineup-arglist} for further |
| 5437 | discussion of this ``DWIM'' measure. |
| 5438 | |
| 5439 | @workswith Almost all symbols, but are typically most useful on |
| 5440 | @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and |
| 5441 | @code{arglist-cont-nonempty}. |
| 5442 | @end defun |
| 5443 | |
| 5444 | @comment ------------------------------------------------------------ |
| 5445 | |
| 5446 | @defun c-indent-one-line-block |
| 5447 | @findex indent-one-line-block (c-) |
| 5448 | Indent a one line block @code{c-basic-offset} extra. E.g: |
| 5449 | |
| 5450 | @example |
| 5451 | @group |
| 5452 | if (n > 0) |
| 5453 | @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} |
| 5454 | @sssTBasicOffset{} |
| 5455 | @end group |
| 5456 | @end example |
| 5457 | |
| 5458 | @noindent |
| 5459 | and |
| 5460 | |
| 5461 | @example |
| 5462 | @group |
| 5463 | if (n > 0) |
| 5464 | @{ @hereFn{c-indent-one-line-block} |
| 5465 | m+=n; n=0; |
| 5466 | @} |
| 5467 | @end group |
| 5468 | @end example |
| 5469 | |
| 5470 | The block may be surrounded by any kind of parenthesis characters. |
| 5471 | @code{nil} is returned if the line doesn't start with a one line block, |
| 5472 | which makes the function usable in list expressions. |
| 5473 | |
| 5474 | @workswith Almost all syntactic symbols, but most useful on the |
| 5475 | @code{-open} symbols. |
| 5476 | @end defun |
| 5477 | |
| 5478 | @comment ------------------------------------------------------------ |
| 5479 | |
| 5480 | @defun c-indent-multi-line-block |
| 5481 | @findex indent-multi-line-block (c-) |
| 5482 | Indent a multiline block @code{c-basic-offset} extra. E.g: |
| 5483 | |
| 5484 | @example |
| 5485 | @group |
| 5486 | int *foo[] = @{ |
| 5487 | NULL, |
| 5488 | @{17@}, @hereFn{c-indent-multi-line-block} |
| 5489 | @end group |
| 5490 | @end example |
| 5491 | |
| 5492 | @noindent |
| 5493 | and |
| 5494 | |
| 5495 | @example |
| 5496 | @group |
| 5497 | int *foo[] = @{ |
| 5498 | NULL, |
| 5499 | @{ @hereFn{c-indent-multi-line-block} |
| 5500 | 17 |
| 5501 | @}, |
| 5502 | @sssTBasicOffset{} |
| 5503 | @end group |
| 5504 | @end example |
| 5505 | |
| 5506 | The block may be surrounded by any kind of parenthesis characters. |
| 5507 | @code{nil} is returned if the line doesn't start with a multiline |
| 5508 | block, which makes the function usable in list expressions. |
| 5509 | |
| 5510 | @workswith Almost all syntactic symbols, but most useful on the |
| 5511 | @code{-open} symbols. |
| 5512 | @end defun |
| 5513 | |
| 5514 | @comment ------------------------------------------------------------ |
| 5515 | |
| 5516 | @defun c-lineup-runin-statements |
| 5517 | @findex lineup-runin-statements (c-) |
| 5518 | Line up statements for coding standards which place the first statement |
| 5519 | in a block on the same line as the block opening brace@footnote{Run-in |
| 5520 | style doesn't really work too well. You might need to write your own |
| 5521 | custom line-up functions to better support this style.}. E.g: |
| 5522 | |
| 5523 | @example |
| 5524 | @group |
| 5525 | int main() |
| 5526 | @{ puts ("Hello!"); |
| 5527 | return 0; @hereFn{c-lineup-runin-statements} |
| 5528 | @} |
| 5529 | @end group |
| 5530 | @end example |
| 5531 | |
| 5532 | If there is no statement after the opening brace to align with, |
| 5533 | @code{nil} is returned. This makes the function usable in list |
| 5534 | expressions. |
| 5535 | |
| 5536 | @workswith The @code{statement} syntactic symbol. |
| 5537 | @end defun |
| 5538 | |
| 5539 | @comment ------------------------------------------------------------ |
| 5540 | |
| 5541 | @defun c-lineup-inexpr-block |
| 5542 | @findex lineup-inexpr-block (c-) |
| 5543 | This can be used with the in-expression block symbols to indent the |
| 5544 | whole block to the column where the construct is started. E.g. for Java |
| 5545 | anonymous classes, this lines up the class under the @samp{new} keyword, |
| 5546 | and in Pike it lines up the lambda function body under the @samp{lambda} |
| 5547 | keyword. Returns @code{nil} if the block isn't part of such a |
| 5548 | construct. |
| 5549 | |
| 5550 | @workswith @code{inlambda}, @code{inexpr-statement}, |
| 5551 | @code{inexpr-class}. |
| 5552 | @end defun |
| 5553 | |
| 5554 | @comment ------------------------------------------------------------ |
| 5555 | |
| 5556 | @defun c-lineup-after-whitesmith-blocks |
| 5557 | @findex lineup-after-whitesmith-blocks (c-) |
| 5558 | Compensate for Whitesmith style indentation of blocks. Due to the way |
| 5559 | @ccmode{} calculates anchor positions for normal lines inside blocks, |
| 5560 | this function is necessary for those lines to get correct Whitesmith |
| 5561 | style indentation. Consider the following examples: |
| 5562 | |
| 5563 | @example |
| 5564 | @group |
| 5565 | int foo() |
| 5566 | @{ |
| 5567 | a; |
| 5568 | x; @hereFn{c-lineup-after-whitesmith-blocks} |
| 5569 | @end group |
| 5570 | @end example |
| 5571 | |
| 5572 | @example |
| 5573 | @group |
| 5574 | int foo() |
| 5575 | @{ |
| 5576 | @{ |
| 5577 | a; |
| 5578 | @} |
| 5579 | x; @hereFn{c-lineup-after-whitesmith-blocks} |
| 5580 | @end group |
| 5581 | @end example |
| 5582 | |
| 5583 | The fact that the line with @code{x} is preceded by a Whitesmith style |
| 5584 | indented block in the latter case and not the first should not affect |
| 5585 | its indentation. But since CC Mode in cases like this uses the |
| 5586 | indentation of the preceding statement as anchor position, the @code{x} |
| 5587 | would in the second case be indented too much if the offset for |
| 5588 | @code{statement} was set simply to zero. |
| 5589 | |
| 5590 | This lineup function corrects for this situation by detecting if the |
| 5591 | anchor position is at an open paren character. In that case, it instead |
| 5592 | indents relative to the surrounding block just like |
| 5593 | @code{c-lineup-whitesmith-in-block}. |
| 5594 | |
| 5595 | @workswith @code{brace-list-entry}, @code{brace-entry-open}, |
| 5596 | @code{statement}, @code{arglist-cont}. |
| 5597 | @end defun |
| 5598 | |
| 5599 | @comment ------------------------------------------------------------ |
| 5600 | |
| 5601 | @defun c-lineup-whitesmith-in-block |
| 5602 | @findex lineup-whitesmith-in-block (c-) |
| 5603 | Line up lines inside a block in Whitesmith style. It's done in a way |
| 5604 | that works both when the opening brace hangs and when it doesn't. E.g: |
| 5605 | |
| 5606 | @example |
| 5607 | @group |
| 5608 | something |
| 5609 | @{ |
| 5610 | foo; @hereFn{c-lineup-whitesmith-in-block} |
| 5611 | @} |
| 5612 | @end group |
| 5613 | @end example |
| 5614 | |
| 5615 | @noindent |
| 5616 | and |
| 5617 | |
| 5618 | @example |
| 5619 | @group |
| 5620 | something @{ |
| 5621 | foo; @hereFn{c-lineup-whitesmith-in-block} |
| 5622 | @} |
| 5623 | @sssTBasicOffset{} |
| 5624 | @end group |
| 5625 | @end example |
| 5626 | |
| 5627 | In the first case the indentation is kept unchanged, in the second |
| 5628 | @code{c-basic-offset} is added. |
| 5629 | |
| 5630 | @workswith @code{defun-close}, @code{defun-block-intro}, |
| 5631 | @code{inline-close}, @code{block-close}, @code{brace-list-close}, |
| 5632 | @code{brace-list-intro}, @code{statement-block-intro}, |
| 5633 | @code{arglist-intro}, @code{arglist-cont-nonempty}, |
| 5634 | @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} |
| 5635 | and @code{inextern-lang}. |
| 5636 | @end defun |
| 5637 | |
| 5638 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5639 | @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions |
| 5640 | @comment node-name, next, previous, up |
| 5641 | @subsection List Line-Up Functions |
| 5642 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5643 | |
| 5644 | The line-up functions here calculate the indentation for lines which |
| 5645 | form lists of items, usually separated by commas. |
| 5646 | |
| 5647 | The function @ref{c-lineup-arglist-close-under-paren}, which is mainly |
| 5648 | for indenting a close parenthesis, is also useful for the lines |
| 5649 | contained within parentheses. |
| 5650 | |
| 5651 | @defun c-lineup-arglist |
| 5652 | @findex lineup-arglist (c-) |
| 5653 | Line up the current argument line under the first argument. |
| 5654 | |
| 5655 | As a special case, if an argument on the same line as the open |
| 5656 | parenthesis starts with a brace block opener, the indentation is |
| 5657 | @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in |
| 5658 | cases like macros that contain statement blocks, e.g: |
| 5659 | |
| 5660 | @example |
| 5661 | @group |
| 5662 | A_VERY_LONG_MACRO_NAME (@{ |
| 5663 | some (code, with + long, lines * in[it]); |
| 5664 | @}); |
| 5665 | @sssTBasicOffset{} |
| 5666 | @end group |
| 5667 | @end example |
| 5668 | |
| 5669 | This is motivated partly because it's more in line with how code |
| 5670 | blocks are handled, and partly since it approximates the behavior of |
| 5671 | earlier CC Mode versions, which due to inaccurate analysis tended to |
| 5672 | indent such cases this way. |
| 5673 | |
| 5674 | @workswith @code{arglist-cont-nonempty}, @code{arglist-close}. |
| 5675 | @end defun |
| 5676 | |
| 5677 | @comment ------------------------------------------------------------ |
| 5678 | |
| 5679 | @defun c-lineup-arglist-intro-after-paren |
| 5680 | @findex lineup-arglist-intro-after-paren (c-) |
| 5681 | Line up a line to just after the open paren of the surrounding paren or |
| 5682 | brace block. |
| 5683 | |
| 5684 | @workswith @code{defun-block-intro}, @code{brace-list-intro}, |
| 5685 | @code{statement-block-intro}, @code{statement-case-intro}, |
| 5686 | @code{arglist-intro}. |
| 5687 | @end defun |
| 5688 | |
| 5689 | @comment ------------------------------------------------------------ |
| 5690 | |
| 5691 | @defun c-lineup-multi-inher |
| 5692 | @findex lineup-multi-inher (c-) |
| 5693 | Line up the classes in C++ multiple inheritance clauses and member |
| 5694 | initializers under each other. E.g: |
| 5695 | |
| 5696 | @example |
| 5697 | @group |
| 5698 | Foo::Foo (int a, int b): |
| 5699 | Cyphr (a), |
| 5700 | Bar (b) @hereFn{c-lineup-multi-inher} |
| 5701 | @end group |
| 5702 | @end example |
| 5703 | |
| 5704 | @noindent |
| 5705 | and |
| 5706 | |
| 5707 | @example |
| 5708 | @group |
| 5709 | class Foo |
| 5710 | : public Cyphr, |
| 5711 | public Bar @hereFn{c-lineup-multi-inher} |
| 5712 | @end group |
| 5713 | @end example |
| 5714 | |
| 5715 | @noindent |
| 5716 | and |
| 5717 | |
| 5718 | @example |
| 5719 | @group |
| 5720 | Foo::Foo (int a, int b) |
| 5721 | : Cyphr (a) |
| 5722 | , Bar (b) @hereFn{c-lineup-multi-inher} |
| 5723 | @end group |
| 5724 | @end example |
| 5725 | |
| 5726 | @workswith @code{inher-cont}, @code{member-init-cont}. |
| 5727 | @end defun |
| 5728 | |
| 5729 | @comment ------------------------------------------------------------ |
| 5730 | |
| 5731 | @defun c-lineup-java-inher |
| 5732 | @findex lineup-java-inher (c-) |
| 5733 | Line up Java implements and extends declarations. If class names |
| 5734 | follow on the same line as the @samp{implements}/@samp{extends} |
| 5735 | keyword, they are lined up under each other. Otherwise, they are |
| 5736 | indented by adding @code{c-basic-offset} to the column of the keyword. |
| 5737 | E.g: |
| 5738 | |
| 5739 | @example |
| 5740 | @group |
| 5741 | class Foo |
| 5742 | extends |
| 5743 | Bar @hereFn{c-lineup-java-inher} |
| 5744 | @sssTBasicOffset{} |
| 5745 | @end group |
| 5746 | @end example |
| 5747 | |
| 5748 | @noindent |
| 5749 | and |
| 5750 | |
| 5751 | @example |
| 5752 | @group |
| 5753 | class Foo |
| 5754 | extends Cyphr, |
| 5755 | Bar @hereFn{c-lineup-java-inher} |
| 5756 | @end group |
| 5757 | @end example |
| 5758 | |
| 5759 | @workswith @code{inher-cont}. |
| 5760 | @end defun |
| 5761 | |
| 5762 | @comment ------------------------------------------------------------ |
| 5763 | |
| 5764 | @defun c-lineup-java-throws |
| 5765 | @findex lineup-java-throws (c-) |
| 5766 | Line up Java throws declarations. If exception names follow on the |
| 5767 | same line as the throws keyword, they are lined up under each other. |
| 5768 | Otherwise, they are indented by adding @code{c-basic-offset} to the |
| 5769 | column of the @samp{throws} keyword. The @samp{throws} keyword itself |
| 5770 | is also indented by @code{c-basic-offset} from the function declaration |
| 5771 | start if it doesn't hang. E.g: |
| 5772 | |
| 5773 | @example |
| 5774 | @group |
| 5775 | int foo() |
| 5776 | throws @hereFn{c-lineup-java-throws} |
| 5777 | Bar @hereFn{c-lineup-java-throws} |
| 5778 | @sssTsssTBasicOffset{} |
| 5779 | @end group |
| 5780 | @end example |
| 5781 | |
| 5782 | @noindent |
| 5783 | and |
| 5784 | |
| 5785 | @example |
| 5786 | @group |
| 5787 | int foo() throws Cyphr, |
| 5788 | Bar, @hereFn{c-lineup-java-throws} |
| 5789 | Vlod @hereFn{c-lineup-java-throws} |
| 5790 | @end group |
| 5791 | @end example |
| 5792 | |
| 5793 | @workswith @code{func-decl-cont}. |
| 5794 | @end defun |
| 5795 | |
| 5796 | @comment ------------------------------------------------------------ |
| 5797 | |
| 5798 | @defun c-lineup-template-args |
| 5799 | @findex lineup-template-args (c-) |
| 5800 | Line up the arguments of a template argument list under each other, but |
| 5801 | only in the case where the first argument is on the same line as the |
| 5802 | opening @samp{<}. |
| 5803 | |
| 5804 | To allow this function to be used in a list expression, @code{nil} is |
| 5805 | returned if there's no template argument on the first line. |
| 5806 | |
| 5807 | @workswith @code{template-args-cont}. |
| 5808 | @end defun |
| 5809 | |
| 5810 | @comment ------------------------------------------------------------ |
| 5811 | |
| 5812 | @defun c-lineup-ObjC-method-call |
| 5813 | @findex lineup-ObjC-method-call (c-) |
| 5814 | For Objective-C code, line up selector args as Emacs Lisp mode does |
| 5815 | with function args: go to the position right after the message receiver, |
| 5816 | and if you are at the end of the line, indent the current line |
| 5817 | c-basic-offset columns from the opening bracket; otherwise you are |
| 5818 | looking at the first character of the first method call argument, so |
| 5819 | lineup the current line with it. |
| 5820 | |
| 5821 | @workswith @code{objc-method-call-cont}. |
| 5822 | @end defun |
| 5823 | |
| 5824 | @comment ------------------------------------------------------------ |
| 5825 | |
| 5826 | @defun c-lineup-ObjC-method-args |
| 5827 | @findex lineup-ObjC-method-args (c-) |
| 5828 | For Objective-C code, line up the colons that separate args. The colon |
| 5829 | on the current line is aligned with the one on the first line. |
| 5830 | |
| 5831 | @workswith @code{objc-method-args-cont}. |
| 5832 | @end defun |
| 5833 | |
| 5834 | @comment ------------------------------------------------------------ |
| 5835 | |
| 5836 | @defun c-lineup-ObjC-method-args-2 |
| 5837 | @findex lineup-ObjC-method-args-2 (c-) |
| 5838 | Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on |
| 5839 | the current line with the colon on the previous line. |
| 5840 | |
| 5841 | @workswith @code{objc-method-args-cont}. |
| 5842 | @end defun |
| 5843 | |
| 5844 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5845 | @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions |
| 5846 | @comment node-name, next, previous, up |
| 5847 | @subsection Operator Line-Up Functions |
| 5848 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5849 | |
| 5850 | The line-up functions here calculate the indentation for lines which |
| 5851 | start with an operator, by lining it up with something on the previous |
| 5852 | line. |
| 5853 | |
| 5854 | @defun c-lineup-argcont |
| 5855 | @findex lineup-argcont (c-) |
| 5856 | Line up a continued argument. E.g: |
| 5857 | |
| 5858 | @example |
| 5859 | @group |
| 5860 | foo (xyz, aaa + bbb + ccc |
| 5861 | + ddd + eee + fff); @hereFn{c-lineup-argcont} |
| 5862 | @end group |
| 5863 | @end example |
| 5864 | |
| 5865 | Only continuation lines like this are touched, @code{nil} is returned on |
| 5866 | lines which are the start of an argument. |
| 5867 | |
| 5868 | Within a gcc @code{asm} block, @code{:} is recognised as an argument |
| 5869 | separator, but of course only between operand specifications, not in the |
| 5870 | expressions for the operands. |
| 5871 | |
| 5872 | @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5873 | @end defun |
| 5874 | |
| 5875 | @comment ------------------------------------------------------------ |
| 5876 | |
| 5877 | @defun c-lineup-arglist-operators |
| 5878 | @findex lineup-arglist-operators (c-) |
| 5879 | Line up lines starting with an infix operator under the open paren. |
| 5880 | Return @code{nil} on lines that don't start with an operator, to leave |
| 5881 | those cases to other line-up functions. Example: |
| 5882 | |
| 5883 | @example |
| 5884 | @group |
| 5885 | if ( x < 10 |
| 5886 | || at_limit (x, @hereFn{c-lineup-arglist-operators} |
| 5887 | list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} |
| 5888 | ) |
| 5889 | @end group |
| 5890 | @end example |
| 5891 | |
| 5892 | Since this function doesn't do anything for lines without an infix |
| 5893 | operator you typically want to use it together with some other lineup |
| 5894 | settings, e.g. as follows (the @code{arglist-close} setting is just a |
| 5895 | suggestion to get a consistent style): |
| 5896 | |
| 5897 | @example |
| 5898 | (c-set-offset 'arglist-cont |
| 5899 | '(c-lineup-arglist-operators 0)) |
| 5900 | (c-set-offset 'arglist-cont-nonempty |
| 5901 | '(c-lineup-arglist-operators c-lineup-arglist)) |
| 5902 | (c-set-offset 'arglist-close |
| 5903 | '(c-lineup-arglist-close-under-paren)) |
| 5904 | @end example |
| 5905 | |
| 5906 | @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5907 | @end defun |
| 5908 | |
| 5909 | @comment ------------------------------------------------------------ |
| 5910 | |
| 5911 | @defun c-lineup-assignments |
| 5912 | @findex lineup-assignments (c-) |
| 5913 | Line up the current line after the assignment operator on the first line |
| 5914 | in the statement. If there isn't any, return nil to allow stacking with |
| 5915 | other line-up functions. If the current line contains an assignment |
| 5916 | operator too, try to align it with the first one. |
| 5917 | |
| 5918 | @workswith @code{topmost-intro-cont}, @code{statement-cont}, |
| 5919 | @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5920 | |
| 5921 | @end defun |
| 5922 | |
| 5923 | @comment ------------------------------------------------------------ |
| 5924 | |
| 5925 | @defun c-lineup-math |
| 5926 | @findex lineup-math (c-) |
| 5927 | Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} |
| 5928 | if no assignment operator was found on the first line. I.e. this |
| 5929 | function is the same as specifying a list @code{(c-lineup-assignments |
| 5930 | +)}. It's provided for compatibility with old configurations. |
| 5931 | |
| 5932 | @workswith @code{topmost-intro-cont}, @code{statement-cont}, |
| 5933 | @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5934 | @end defun |
| 5935 | |
| 5936 | @comment ------------------------------------------------------------ |
| 5937 | |
| 5938 | @defun c-lineup-cascaded-calls |
| 5939 | @findex lineup-cascaded-calls (c-) |
| 5940 | Line up ``cascaded calls'' under each other. If the line begins with |
| 5941 | @code{->} or @code{.} and the preceding line ends with one or more |
| 5942 | function calls preceded by the same token, then the arrow is lined up |
| 5943 | with the first of those tokens. E.g: |
| 5944 | |
| 5945 | @example |
| 5946 | @group |
| 5947 | r = proc->add(17)->add(18) |
| 5948 | ->add(19) + @hereFn{c-lineup-cascaded-calls} |
| 5949 | offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} |
| 5950 | @end group |
| 5951 | @end example |
| 5952 | |
| 5953 | In any other situation @code{nil} is returned to allow use in list |
| 5954 | expressions. |
| 5955 | |
| 5956 | @workswith @code{topmost-intro-cont}, @code{statement-cont}, |
| 5957 | @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5958 | @end defun |
| 5959 | |
| 5960 | @comment ------------------------------------------------------------ |
| 5961 | |
| 5962 | @defun c-lineup-streamop |
| 5963 | @findex lineup-streamop (c-) |
| 5964 | Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). |
| 5965 | |
| 5966 | @workswith @code{stream-op}. |
| 5967 | @end defun |
| 5968 | |
| 5969 | @comment ------------------------------------------------------------ |
| 5970 | |
| 5971 | @defun c-lineup-string-cont |
| 5972 | @findex lineup-string-cont (c-) |
| 5973 | Line up a continued string under the one it continues. A continued |
| 5974 | string in this sense is where a string literal follows directly after |
| 5975 | another one. E.g: |
| 5976 | |
| 5977 | @example |
| 5978 | @group |
| 5979 | result = prefix + "A message " |
| 5980 | "string."; @hereFn{c-lineup-string-cont} |
| 5981 | @end group |
| 5982 | @end example |
| 5983 | |
| 5984 | @code{nil} is returned in other situations, to allow stacking with other |
| 5985 | lineup functions. |
| 5986 | |
| 5987 | @workswith @code{topmost-intro-cont}, @code{statement-cont}, |
| 5988 | @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 5989 | @end defun |
| 5990 | |
| 5991 | |
| 5992 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5993 | @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions |
| 5994 | @comment node-name, next, previous, up |
| 5995 | @subsection Comment Line-Up Functions |
| 5996 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 5997 | |
| 5998 | The lineup functions here calculate the indentation for several types |
| 5999 | of comment structure. |
| 6000 | |
| 6001 | @defun c-lineup-C-comments |
| 6002 | @findex lineup-C-comments (c-) |
| 6003 | Line up C block comment continuation lines. Various heuristics are used |
| 6004 | to handle most of the common comment styles. Some examples: |
| 6005 | |
| 6006 | @example |
| 6007 | @group |
| 6008 | /* /** /* |
| 6009 | * text * text text |
| 6010 | */ */ */ |
| 6011 | @end group |
| 6012 | @end example |
| 6013 | |
| 6014 | @example |
| 6015 | @group |
| 6016 | /* text /* /** |
| 6017 | text ** text ** text |
| 6018 | */ */ */ |
| 6019 | @end group |
| 6020 | @end example |
| 6021 | |
| 6022 | @example |
| 6023 | @group |
| 6024 | /************************************************** |
| 6025 | * text |
| 6026 | *************************************************/ |
| 6027 | @end group |
| 6028 | @end example |
| 6029 | |
| 6030 | @vindex comment-start-skip |
| 6031 | @example |
| 6032 | @group |
| 6033 | /************************************************** |
| 6034 | Free form text comments: |
| 6035 | In comments with a long delimiter line at the |
| 6036 | start, the indentation is kept unchanged for lines |
| 6037 | that start with an empty comment line prefix. The |
| 6038 | delimiter line is whatever matches the |
| 6039 | @code{comment-start-skip} regexp. |
| 6040 | **************************************************/ |
| 6041 | @end group |
| 6042 | @end example |
| 6043 | |
| 6044 | The style variable @code{c-comment-prefix-regexp} is used to recognize |
| 6045 | the comment line prefix, e.g. the @samp{*} that usually starts every |
| 6046 | line inside a comment. |
| 6047 | |
| 6048 | @workswith The @code{c} syntactic symbol. |
| 6049 | @end defun |
| 6050 | |
| 6051 | @comment ------------------------------------------------------------ |
| 6052 | |
| 6053 | @defun c-lineup-comment |
| 6054 | @findex lineup-comment (c-) |
| 6055 | Line up a comment-only line according to the style variable |
| 6056 | @code{c-comment-only-line-offset}. If the comment is lined up with a |
| 6057 | comment starter on the previous line, that alignment is preserved. |
| 6058 | |
| 6059 | @defopt c-comment-only-line-offset |
| 6060 | @vindex comment-only-line-offset (c-) |
| 6061 | This style variable specifies the extra offset for the line. It can |
| 6062 | contain an integer or a cons cell of the form |
| 6063 | |
| 6064 | @example |
| 6065 | (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) |
| 6066 | @end example |
| 6067 | |
| 6068 | @noindent |
| 6069 | where @var{non-anchored-offset} is the amount of offset given to |
| 6070 | non-column-zero anchored lines, and @var{anchored-offset} is the amount |
| 6071 | of offset to give column-zero anchored lines. Just an integer as value |
| 6072 | is equivalent to @code{(@r{@var{value}} . -1000)}. |
| 6073 | @end defopt |
| 6074 | |
| 6075 | @workswith @code{comment-intro}. |
| 6076 | @end defun |
| 6077 | |
| 6078 | @comment ------------------------------------------------------------ |
| 6079 | |
| 6080 | @defun c-lineup-knr-region-comment |
| 6081 | @findex lineup-knr-region-comment (c-) |
| 6082 | Line up a comment in the ``K&R region'' with the declaration. That is |
| 6083 | the region between the function or class header and the beginning of the |
| 6084 | block. E.g: |
| 6085 | |
| 6086 | @example |
| 6087 | @group |
| 6088 | int main() |
| 6089 | /* Called at startup. */ @hereFn{c-lineup-knr-region-comment} |
| 6090 | @{ |
| 6091 | return 0; |
| 6092 | @} |
| 6093 | @end group |
| 6094 | @end example |
| 6095 | |
| 6096 | Return @code{nil} if called in any other situation, to be useful in list |
| 6097 | expressions. |
| 6098 | |
| 6099 | @workswith @code{comment-intro}. |
| 6100 | @end defun |
| 6101 | |
| 6102 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6103 | @node Misc Line-Up, , Comment Line-Up, Line-Up Functions |
| 6104 | @comment node-name, next, previous, up |
| 6105 | @subsection Miscellaneous Line-Up Functions |
| 6106 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6107 | |
| 6108 | The line-up functions here are the odds and ends which didn't fit into |
| 6109 | any earlier category. |
| 6110 | |
| 6111 | @defun c-lineup-dont-change |
| 6112 | @findex lineup-dont-change (c-) |
| 6113 | This lineup function makes the line stay at whatever indentation it |
| 6114 | already has; think of it as an identity function for lineups. |
| 6115 | |
| 6116 | @workswith Any syntactic symbol. |
| 6117 | @end defun |
| 6118 | |
| 6119 | @comment ------------------------------------------------------------ |
| 6120 | |
| 6121 | @defun c-lineup-cpp-define |
| 6122 | @findex lineup-cpp-define (c-) |
| 6123 | Line up macro continuation lines according to the indentation of the |
| 6124 | construct preceding the macro. E.g: |
| 6125 | |
| 6126 | @example |
| 6127 | @group |
| 6128 | const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} |
| 6129 | \"Some text.\"; |
| 6130 | |
| 6131 | #define X(A, B) \ |
| 6132 | do @{ \ @hereFn{c-lineup-cpp-define} |
| 6133 | printf (A, B); \ |
| 6134 | @} while (0) |
| 6135 | @end group |
| 6136 | @end example |
| 6137 | |
| 6138 | @noindent |
| 6139 | and: |
| 6140 | |
| 6141 | @example |
| 6142 | @group |
| 6143 | int dribble() @{ |
| 6144 | if (!running) @hereFn{@r{The beginning of the preceding construct.}} |
| 6145 | error(\"Not running!\"); |
| 6146 | |
| 6147 | #define X(A, B) \ |
| 6148 | do @{ \ @hereFn{c-lineup-cpp-define} |
| 6149 | printf (A, B); \ |
| 6150 | @} while (0) |
| 6151 | @end group |
| 6152 | @end example |
| 6153 | |
| 6154 | If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the |
| 6155 | function returns the relative indentation to the macro start line to |
| 6156 | allow accumulation with other offsets. E.g. in the following cases, |
| 6157 | @code{cpp-define-intro} is combined with the |
| 6158 | @code{statement-block-intro} that comes from the @samp{do @{} that hangs |
| 6159 | on the @samp{#define} line: |
| 6160 | |
| 6161 | @example |
| 6162 | @group |
| 6163 | const char msg[] = |
| 6164 | \"Some text.\"; |
| 6165 | |
| 6166 | #define X(A, B) do @{ \ |
| 6167 | printf (A, B); \ @hereFn{c-lineup-cpp-define} |
| 6168 | this->refs++; \ |
| 6169 | @} while (0) @hereFn{c-lineup-cpp-define} |
| 6170 | @end group |
| 6171 | @end example |
| 6172 | |
| 6173 | @noindent |
| 6174 | and: |
| 6175 | |
| 6176 | @example |
| 6177 | @group |
| 6178 | int dribble() @{ |
| 6179 | if (!running) |
| 6180 | error(\"Not running!\"); |
| 6181 | |
| 6182 | #define X(A, B) do @{ \ |
| 6183 | printf (A, B); \ @hereFn{c-lineup-cpp-define} |
| 6184 | this->refs++; \ |
| 6185 | @} while (0) @hereFn{c-lineup-cpp-define} |
| 6186 | @end group |
| 6187 | @end example |
| 6188 | |
| 6189 | The relative indentation returned by @code{c-lineup-cpp-define} is zero |
| 6190 | and two, respectively, on the two lines in each of these examples. They |
| 6191 | are then added to the two column indentation that |
| 6192 | @code{statement-block-intro} gives in both cases here. |
| 6193 | |
| 6194 | If the relative indentation is zero, then @code{nil} is returned |
| 6195 | instead. That is useful in a list expression to specify the default |
| 6196 | indentation on the top level. |
| 6197 | |
| 6198 | If @code{c-syntactic-indentation-in-macros} is @code{nil} then this |
| 6199 | function keeps the current indentation, except for empty lines (ignoring |
| 6200 | the ending backslash) where it takes the indentation from the closest |
| 6201 | preceding nonempty line in the macro. If there's no such line in the |
| 6202 | macro then the indentation is taken from the construct preceding it, as |
| 6203 | described above. |
| 6204 | |
| 6205 | @workswith @code{cpp-define-intro}. |
| 6206 | @end defun |
| 6207 | |
| 6208 | @comment ------------------------------------------------------------ |
| 6209 | |
| 6210 | @defun c-lineup-gcc-asm-reg |
| 6211 | @findex lineup-gcc-asm-reg (c-) |
| 6212 | Line up a gcc asm register under one on a previous line. |
| 6213 | |
| 6214 | @example |
| 6215 | @group |
| 6216 | asm ("foo %1, %0\n" |
| 6217 | "bar %0, %1" |
| 6218 | : "=r" (w), |
| 6219 | "=r" (x) |
| 6220 | : "0" (y), |
| 6221 | "1" (z)); |
| 6222 | @end group |
| 6223 | @end example |
| 6224 | |
| 6225 | The @samp{x} line is aligned to the text after the @samp{:} on the |
| 6226 | @samp{w} line, and similarly @samp{z} under @samp{y}. |
| 6227 | |
| 6228 | This is done only in an @samp{asm} or @samp{__asm__} block, and only to |
| 6229 | those lines mentioned. Anywhere else @code{nil} is returned. The usual |
| 6230 | arrangement is to have this routine as an extra feature at the start of |
| 6231 | arglist lineups, e.g. |
| 6232 | |
| 6233 | @example |
| 6234 | (c-lineup-gcc-asm-reg c-lineup-arglist) |
| 6235 | @end example |
| 6236 | |
| 6237 | @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. |
| 6238 | @end defun |
| 6239 | |
| 6240 | @comment ------------------------------------------------------------ |
| 6241 | |
| 6242 | @defun c-lineup-topmost-intro-cont |
| 6243 | @findex lineup-topmost-intro-cont (c-) |
| 6244 | Line up declaration continuation lines zero or one indentation |
| 6245 | step@footnote{This function is mainly provided to mimic the behavior of |
| 6246 | CC Mode 5.28 and earlier where this case wasn't handled consistently so |
| 6247 | that those lines could be analyzed as either topmost-intro-cont or |
| 6248 | statement-cont. It's used for @code{topmost-intro-cont} by default, but |
| 6249 | you might consider using @code{+} instead.}. For lines preceding a |
| 6250 | definition, zero is used. For other lines, @code{c-basic-offset} is |
| 6251 | added to the indentation. E.g: |
| 6252 | |
| 6253 | @example |
| 6254 | @group |
| 6255 | int |
| 6256 | neg (int i) @hereFn{c-lineup-topmost-intro-cont} |
| 6257 | @{ |
| 6258 | return -i; |
| 6259 | @} |
| 6260 | @end group |
| 6261 | @end example |
| 6262 | |
| 6263 | @noindent |
| 6264 | and |
| 6265 | |
| 6266 | @example |
| 6267 | @group |
| 6268 | struct |
| 6269 | larch @hereFn{c-lineup-topmost-intro-cont} |
| 6270 | @{ |
| 6271 | double height; |
| 6272 | @} |
| 6273 | the_larch, @hereFn{c-lineup-topmost-intro-cont} |
| 6274 | another_larch; @hereFn{c-lineup-topmost-intro-cont} |
| 6275 | @sssTBasicOffset{} |
| 6276 | @end group |
| 6277 | @end example |
| 6278 | |
| 6279 | @noindent |
| 6280 | and |
| 6281 | |
| 6282 | @example |
| 6283 | @group |
| 6284 | struct larch |
| 6285 | the_larch, @hereFn{c-lineup-topmost-intro-cont} |
| 6286 | another_larch; @hereFn{c-lineup-topmost-intro-cont} |
| 6287 | @end group |
| 6288 | @end example |
| 6289 | |
| 6290 | @workswith @code{topmost-intro-cont}. |
| 6291 | @end defun |
| 6292 | |
| 6293 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6294 | @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation |
| 6295 | @comment node-name, next, previous, up |
| 6296 | @section Custom Line-Up Functions |
| 6297 | @cindex customization, indentation functions |
| 6298 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6299 | |
| 6300 | The most flexible way to customize indentation is by writing custom |
| 6301 | line-up functions, and associating them with specific syntactic |
| 6302 | symbols (@pxref{c-offsets-alist}). Depending on the effect you want, |
| 6303 | it might be better to write a @code{c-special-indent-hook} function |
| 6304 | rather than a line-up function (@pxref{Other Indentation}). |
| 6305 | |
| 6306 | @ccmode{} comes with an extensive set of predefined line-up functions, |
| 6307 | not all of which are used by the default styles. So there's a good |
| 6308 | chance the function you want already exists. @xref{Line-Up |
| 6309 | Functions}, for a list of them. If you write your own line-up |
| 6310 | function, it's probably a good idea to start working from one of these |
| 6311 | predefined functions, which can be found in the file |
| 6312 | @file{cc-align.el}. If you have written a line-up function that you |
| 6313 | think is generally useful, you're very welcome to contribute it; |
| 6314 | please contact @email{bug-cc-mode@@gnu.org}. |
| 6315 | |
| 6316 | Line-up functions are passed a single argument, the syntactic |
| 6317 | element (see below). The return value is a @code{c-offsets-alist} |
| 6318 | offset specification: for example, an integer, a symbol such as |
| 6319 | @code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful |
| 6320 | when the offset specification for a syntactic element is a list |
| 6321 | containing the line-up function (@pxref{c-offsets-alist}).}, or even |
| 6322 | another line-up function. Full details of these are in |
| 6323 | @ref{c-offsets-alist}. |
| 6324 | |
| 6325 | Line-up functions must not move point or change the content of the |
| 6326 | buffer (except temporarily). They are however allowed to do |
| 6327 | @dfn{hidden buffer changes}, i.e. setting text properties for caching |
| 6328 | purposes etc. Buffer undo recording is disabled while they run. |
| 6329 | |
| 6330 | The syntactic element passed as the parameter to a line-up function is |
| 6331 | a cons cell of the form |
| 6332 | |
| 6333 | @example |
| 6334 | (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) |
| 6335 | @end example |
| 6336 | |
| 6337 | @noindent |
| 6338 | @c FIXME!!! The following sentence might be better omitted, since the |
| 6339 | @c information is in the cross reference "Syntactic Analysis". 2005/10/2. |
| 6340 | where @var{syntactic-symbol} is the symbol that the function was |
| 6341 | called for, and @var{anchor-position} is the anchor position (if any) |
| 6342 | for the construct that triggered the syntactic symbol |
| 6343 | (@pxref{Syntactic Analysis}). This cons cell is how the syntactic |
| 6344 | element of a line used to be represented in @ccmode{} 5.28 and |
| 6345 | earlier. Line-up functions are still passed this cons cell, so as to |
| 6346 | preserve compatibility with older configurations. In the future, we |
| 6347 | may decide to convert to using the full list format---you can prepare |
| 6348 | your setup for this by using the access functions |
| 6349 | (@code{c-langelem-sym}, etc.) described below. |
| 6350 | |
| 6351 | @vindex c-syntactic-element |
| 6352 | @vindex syntactic-element (c-) |
| 6353 | @vindex c-syntactic-context |
| 6354 | @vindex syntactic-context (c-) |
| 6355 | Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more |
| 6356 | info in the syntactic element - typically other positions that can be |
| 6357 | interesting besides the anchor position. That info can't be accessed |
| 6358 | through the passed argument, which is a cons cell. Instead, you can |
| 6359 | get this information from the variable @code{c-syntactic-element}, |
| 6360 | which is dynamically bound to the complete syntactic element. The |
| 6361 | variable @code{c-syntactic-context} might also be useful - it gets |
| 6362 | dynamically bound to the complete syntactic context. @xref{Custom |
| 6363 | Braces}. |
| 6364 | |
| 6365 | @ccmode{} provides a few functions to access parts of syntactic |
| 6366 | elements in a more abstract way. Besides making the code easier to |
| 6367 | read, they also hide the difference between the old cons cell form |
| 6368 | used in the line-up function argument and the new list form used in |
| 6369 | @code{c-syntactic-element} and everywhere else. The functions are: |
| 6370 | |
| 6371 | @defun c-langelem-sym langelem |
| 6372 | @findex langelem-sym (c-) |
| 6373 | Return the syntactic symbol in @var{langelem}. |
| 6374 | @end defun |
| 6375 | |
| 6376 | @defun c-langelem-pos langelem |
| 6377 | @findex langelem-pos (c-) |
| 6378 | Return the anchor position in @var{langelem}, or nil if there is none. |
| 6379 | @end defun |
| 6380 | |
| 6381 | @defun c-langelem-col langelem &optional preserve-point |
| 6382 | @findex langelem-col (c-) |
| 6383 | Return the column of the anchor position in @var{langelem}. Also move |
| 6384 | the point to that position unless @var{preserve-point} is |
| 6385 | non-@code{nil}. |
| 6386 | @end defun |
| 6387 | |
| 6388 | @defun c-langelem-2nd-pos langelem |
| 6389 | @findex langelem-2nd-pos (c-) |
| 6390 | Return the secondary position in @var{langelem}, or @code{nil} if there |
| 6391 | is none. |
| 6392 | |
| 6393 | Note that the return value of this function is always @code{nil} if |
| 6394 | @var{langelem} is in the old cons cell form. Thus this function is |
| 6395 | only meaningful when used on syntactic elements taken from |
| 6396 | @code{c-syntactic-element} or @code{c-syntactic-context}. |
| 6397 | @end defun |
| 6398 | |
| 6399 | Custom line-up functions can be as simple or as complex as you like, and |
| 6400 | any syntactic symbol that appears in @code{c-offsets-alist} can have a |
| 6401 | custom line-up function associated with it. |
| 6402 | |
| 6403 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6404 | @node Other Indentation, , Custom Line-Up, Customizing Indentation |
| 6405 | @comment node-name, next, previous, up |
| 6406 | @section Other Special Indentations |
| 6407 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6408 | |
| 6409 | Here are the remaining odds and ends regarding indentation: |
| 6410 | |
| 6411 | @defopt c-label-minimum-indentation |
| 6412 | @vindex label-minimum-indentation (c-) |
| 6413 | In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is |
| 6414 | imposed on lines inside code blocks. This minimum indentation is |
| 6415 | controlled by this style variable. The default value is 1. |
| 6416 | |
| 6417 | @findex c-gnu-impose-minimum |
| 6418 | @findex gnu-impose-minimum (c-) |
| 6419 | It's the function @code{c-gnu-impose-minimum} that enforces this minimum |
| 6420 | indentation. It must be present on @code{c-special-indent-hook} to |
| 6421 | work. |
| 6422 | @end defopt |
| 6423 | |
| 6424 | @defopt c-special-indent-hook |
| 6425 | @vindex special-indent-hook (c-) |
| 6426 | This style variable is a standard hook variable that is called after |
| 6427 | every line is indented by @ccmode{}. It is called only if |
| 6428 | @code{c-syntactic-indentation} is non-@code{nil} (which it is by |
| 6429 | default (@pxref{Indentation Engine Basics})). You can put a function |
| 6430 | on this hook to do any special indentation or ad hoc line adjustments |
| 6431 | your style dictates, such as adding extra indentation to constructors |
| 6432 | or destructor declarations in a class definition, etc. Sometimes it |
| 6433 | is better to write a custom Line-up Function instead (@pxref{Custom |
| 6434 | Line-Up}). |
| 6435 | |
| 6436 | When the indentation engine calls this hook, the variable |
| 6437 | @code{c-syntactic-context} is bound to the current syntactic context |
| 6438 | (i.e. what you would get by typing @kbd{C-c C-s} on the source line. |
| 6439 | @xref{Custom Braces}.). Note that you should not change point or mark |
| 6440 | inside a @code{c-special-indent-hook} function, i.e. you'll probably |
| 6441 | want to wrap your function in a @code{save-excursion}@footnote{The |
| 6442 | numerical value returned by @code{point} will change if you change the |
| 6443 | indentation of the line within a @code{save-excursion} form, but point |
| 6444 | itself will still be over the same piece of text.}. |
| 6445 | |
| 6446 | Setting @code{c-special-indent-hook} in style definitions is handled |
| 6447 | slightly differently from other variables---A style can only add |
| 6448 | functions to this hook, not remove them. @xref{Style Variables}. |
| 6449 | @end defopt |
| 6450 | |
| 6451 | |
| 6452 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6453 | @node Custom Macros, Odds and Ends, Customizing Indentation, Top |
| 6454 | @comment node-name, next, previous, up |
| 6455 | @chapter Customizing Macros |
| 6456 | @cindex macros |
| 6457 | @cindex preprocessor directives |
| 6458 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6459 | |
| 6460 | Normally, the lines in a multi-line macro are indented relative to |
| 6461 | each other as though they were code. You can suppress this behavior |
| 6462 | by setting the following user option: |
| 6463 | |
| 6464 | @defopt c-syntactic-indentation-in-macros |
| 6465 | @vindex syntactic-indentation-in-macros (c-) |
| 6466 | Enable syntactic analysis inside macros, which is the default. If this |
| 6467 | is @code{nil}, all lines inside macro definitions are analyzed as |
| 6468 | @code{cpp-macro-cont}. |
| 6469 | @end defopt |
| 6470 | |
| 6471 | @ccmode{} provides some tools to help keep the line continuation |
| 6472 | backslashes in macros neat and tidy. Their precise action is |
| 6473 | customized with these variables: |
| 6474 | |
| 6475 | @defopt c-backslash-column |
| 6476 | @vindex backslash-column (c-) |
| 6477 | @defoptx c-backslash-max-column |
| 6478 | @vindex backslash-max-column (c-) |
| 6479 | These variables control the alignment columns for line continuation |
| 6480 | backslashes in multiline macros. They are used by the functions that |
| 6481 | automatically insert or align such backslashes, |
| 6482 | e.g. @code{c-backslash-region} and @code{c-context-line-break}. |
| 6483 | |
| 6484 | @code{c-backslash-column} specifies the minimum column for the |
| 6485 | backslashes. If any line in the macro goes past this column, then the |
| 6486 | next tab stop (i.e. next multiple of @code{tab-width}) in that line is |
| 6487 | used as the alignment column for all the backslashes, so that they |
| 6488 | remain in a single column. However, if any lines go past |
| 6489 | @code{c-backslash-max-column} then the backslashes in the rest of the |
| 6490 | macro will be kept at that column, so that the lines which are too |
| 6491 | long ``stick out'' instead. |
| 6492 | |
| 6493 | Don't ever set these variables to @code{nil}. If you want to disable |
| 6494 | the automatic alignment of backslashes, use |
| 6495 | @code{c-auto-align-backslashes}. |
| 6496 | @end defopt |
| 6497 | |
| 6498 | @defopt c-auto-align-backslashes |
| 6499 | @vindex auto-align-backslashes (c-) |
| 6500 | Align automatically inserted line continuation backslashes if |
| 6501 | non-@code{nil}. When line continuation backslashes are inserted |
| 6502 | automatically for line breaks in multiline macros, e.g. by |
| 6503 | @code{c-context-line-break}, they are aligned with the other |
| 6504 | backslashes in the same macro if this flag is set. |
| 6505 | |
| 6506 | If @code{c-auto-align-backslashes} is @code{nil}, automatically |
| 6507 | inserted backslashes are preceded by a single space, and backslashes |
| 6508 | get aligned only when you explicitly invoke the command |
| 6509 | @code{c-backslash-region} (@kbd{C-c C-\}). |
| 6510 | @end defopt |
| 6511 | |
| 6512 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6513 | @node Odds and Ends, Sample .emacs File, Custom Macros, Top |
| 6514 | @comment node-name, next, previous, up |
| 6515 | @chapter Odds and Ends |
| 6516 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6517 | |
| 6518 | The stuff that didn't fit in anywhere else is documented here. |
| 6519 | |
| 6520 | @defopt c-require-final-newline |
| 6521 | @vindex require-final-newline (c-) |
| 6522 | Controls whether a final newline is enforced when the file is saved. |
| 6523 | The value is an association list that for each language mode specifies |
| 6524 | the value to give to @code{require-final-newline} (@pxref{Saving |
| 6525 | Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a |
| 6526 | language isn't present on the association list, CC Mode won't touch |
| 6527 | @code{require-final-newline} in buffers for that language. |
| 6528 | |
| 6529 | The default is to set @code{require-final-newline} to @code{t} in the |
| 6530 | languages that mandate that source files should end with newlines. |
| 6531 | These are C, C++ and Objective-C. |
| 6532 | @end defopt |
| 6533 | |
| 6534 | @defopt c-echo-syntactic-information-p |
| 6535 | @vindex echo-syntactic-information-p (c-) |
| 6536 | If non-@code{nil}, the syntactic analysis for the current line is shown |
| 6537 | in the echo area when it's indented (unless |
| 6538 | @code{c-syntactic-indentation} is @code{nil}). That's useful when |
| 6539 | finding out which syntactic symbols to modify to get the indentation you |
| 6540 | want. |
| 6541 | @end defopt |
| 6542 | |
| 6543 | @defopt c-report-syntactic-errors |
| 6544 | @vindex report-syntactic-errors (c-) |
| 6545 | If non-@code{nil}, certain syntactic errors are reported with a ding and |
| 6546 | a message, for example when an @code{else} is indented for which there |
| 6547 | is no corresponding @code{if}. |
| 6548 | |
| 6549 | Note however that @ccmode{} doesn't make any special effort to check for |
| 6550 | syntactic errors; that's the job of the compiler. The reason it can |
| 6551 | report cases like the one above is that it can't find the correct |
| 6552 | anchoring position to indent the line in that case. |
| 6553 | @end defopt |
| 6554 | |
| 6555 | |
| 6556 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6557 | @node Sample .emacs File, Performance Issues, Odds and Ends, Top |
| 6558 | @comment node-name, next, previous, up |
| 6559 | @appendix Sample .emacs File |
| 6560 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6561 | |
| 6562 | Here's a sample .emacs file fragment that might help you along the way. |
| 6563 | Just copy this region and paste it into your .emacs file. You might want |
| 6564 | to change some of the actual values. |
| 6565 | |
| 6566 | @verbatim |
| 6567 | ;; Make a non-standard key binding. We can put this in |
| 6568 | ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, |
| 6569 | ;; inherit from it. |
| 6570 | (defun my-c-initialization-hook () |
| 6571 | (define-key c-mode-base-map "\C-m" 'c-context-line-break)) |
| 6572 | (add-hook 'c-initialization-hook 'my-c-initialization-hook) |
| 6573 | |
| 6574 | ;; offset customizations not in my-c-style |
| 6575 | ;; This will take precedence over any setting of the syntactic symbol |
| 6576 | ;; made by a style. |
| 6577 | (setq c-offsets-alist '((member-init-intro . ++))) |
| 6578 | |
| 6579 | ;; Create my personal style. |
| 6580 | (defconst my-c-style |
| 6581 | '((c-tab-always-indent . t) |
| 6582 | (c-comment-only-line-offset . 4) |
| 6583 | (c-hanging-braces-alist . ((substatement-open after) |
| 6584 | (brace-list-open))) |
| 6585 | (c-hanging-colons-alist . ((member-init-intro before) |
| 6586 | (inher-intro) |
| 6587 | (case-label after) |
| 6588 | (label after) |
| 6589 | (access-label after))) |
| 6590 | (c-cleanup-list . (scope-operator |
| 6591 | empty-defun-braces |
| 6592 | defun-close-semi)) |
| 6593 | (c-offsets-alist . ((arglist-close . c-lineup-arglist) |
| 6594 | (substatement-open . 0) |
| 6595 | (case-label . 4) |
| 6596 | (block-open . 0) |
| 6597 | (knr-argdecl-intro . -))) |
| 6598 | (c-echo-syntactic-information-p . t)) |
| 6599 | "My C Programming Style") |
| 6600 | (c-add-style "PERSONAL" my-c-style) |
| 6601 | |
| 6602 | ;; Customizations for all modes in CC Mode. |
| 6603 | (defun my-c-mode-common-hook () |
| 6604 | ;; set my personal style for the current buffer |
| 6605 | (c-set-style "PERSONAL") |
| 6606 | ;; other customizations |
| 6607 | (setq tab-width 8 |
| 6608 | ;; this will make sure spaces are used instead of tabs |
| 6609 | indent-tabs-mode nil) |
| 6610 | ;; we like auto-newline, but not hungry-delete |
| 6611 | (c-toggle-auto-newline 1)) |
| 6612 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) |
| 6613 | @end verbatim |
| 6614 | |
| 6615 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6616 | @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top |
| 6617 | @comment node-name, next, previous, up |
| 6618 | @chapter Performance Issues |
| 6619 | @cindex performance |
| 6620 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6621 | |
| 6622 | @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. |
| 6623 | |
| 6624 | C and its derivative languages are highly complex creatures. Often, |
| 6625 | ambiguous code situations arise that require @ccmode{} to scan large |
| 6626 | portions of the buffer to determine syntactic context. Such |
| 6627 | pathological code can cause @ccmode{} to perform fairly badly. This |
| 6628 | section gives some insight in how @ccmode{} operates, how that interacts |
| 6629 | with some coding styles, and what you can use to improve performance. |
| 6630 | |
| 6631 | The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take |
| 6632 | more than a fraction of a second) in any interactive operation. |
| 6633 | I.e. it's tuned to limit the maximum response time in single operations, |
| 6634 | which is sometimes at the expense of batch-like operations like |
| 6635 | reindenting whole blocks. If you find that @ccmode{} gradually gets |
| 6636 | slower and slower in certain situations, perhaps as the file grows in |
| 6637 | size or as the macro or comment you're editing gets bigger, then chances |
| 6638 | are that something isn't working right. You should consider reporting |
| 6639 | it, unless it's something that's mentioned in this section. |
| 6640 | |
| 6641 | Because @ccmode{} has to scan the buffer backwards from the current |
| 6642 | insertion point, and because C's syntax is fairly difficult to parse in |
| 6643 | the backwards direction, @ccmode{} often tries to find the nearest |
| 6644 | position higher up in the buffer from which to begin a forward scan |
| 6645 | (it's typically an opening or closing parenthesis of some kind). The |
| 6646 | farther this position is from the current insertion point, the slower it |
| 6647 | gets. |
| 6648 | |
| 6649 | @findex beginning-of-defun |
| 6650 | In earlier versions of @ccmode{}, we used to recommend putting the |
| 6651 | opening brace of a top-level construct@footnote{E.g. a function in C, |
| 6652 | or outermost class definition in C++ or Java.} into the leftmost |
| 6653 | column. Earlier still, this used to be a rigid Emacs constraint, as |
| 6654 | embodied in the @code{beginning-of-defun} function. @ccmode now |
| 6655 | caches syntactic information much better, so that the delay caused by |
| 6656 | searching for such a brace when it's not in column 0 is minimal, |
| 6657 | except perhaps when you've just moved a long way inside the file. |
| 6658 | |
| 6659 | @findex defun-prompt-regexp |
| 6660 | @vindex c-Java-defun-prompt-regexp |
| 6661 | @vindex Java-defun-prompt-regexp (c-) |
| 6662 | A special note about @code{defun-prompt-regexp} in Java mode: The common |
| 6663 | style is to hang the opening braces of functions and classes on the |
| 6664 | right side of the line, and that doesn't work well with the Emacs |
| 6665 | approach. @ccmode{} comes with a constant |
| 6666 | @code{c-Java-defun-prompt-regexp} which tries to define a regular |
| 6667 | expression usable for this style, but there are problems with it. In |
| 6668 | some cases it can cause @code{beginning-of-defun} to hang@footnote{This |
| 6669 | has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, |
| 6670 | it is not used by default, but if you feel adventurous, you can set |
| 6671 | @code{defun-prompt-regexp} to it in your mode hook. In any event, |
| 6672 | setting and relying on @code{defun-prompt-regexp} will definitely slow |
| 6673 | things down because (X)Emacs will be doing regular expression searches a |
| 6674 | lot, so you'll probably be taking a hit either way! |
| 6675 | |
| 6676 | @ccmode{} maintains a cache of the opening parentheses of the blocks |
| 6677 | surrounding the point, and it adapts that cache as the point is moved |
| 6678 | around. That means that in bad cases it can take noticeable time to |
| 6679 | indent a line in a new surrounding, but after that it gets fast as long |
| 6680 | as the point isn't moved far off. The farther the point is moved, the |
| 6681 | less useful is the cache. Since editing typically is done in ``chunks'' |
| 6682 | rather than on single lines far apart from each other, the cache |
| 6683 | typically gives good performance even when the code doesn't fit the |
| 6684 | Emacs approach to finding the defun starts. |
| 6685 | |
| 6686 | @vindex c-enable-xemacs-performance-kludge-p |
| 6687 | @vindex enable-xemacs-performance-kludge-p (c-) |
| 6688 | XEmacs users can set the variable |
| 6689 | @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This |
| 6690 | tells @ccmode{} to use XEmacs-specific built-in functions which, in some |
| 6691 | circumstances, can locate the top-most opening brace much more quickly than |
| 6692 | @code{beginning-of-defun}. Preliminary testing has shown that for |
| 6693 | styles where these braces are hung (e.g. most JDK-derived Java styles), |
| 6694 | this hack can improve performance of the core syntax parsing routines |
| 6695 | from 3 to 60 times. However, for styles which @emph{do} conform to |
| 6696 | Emacs' recommended style of putting top-level braces in column zero, |
| 6697 | this hack can degrade performance by about as much. Thus this variable |
| 6698 | is set to @code{nil} by default, since the Emacs-friendly styles should |
| 6699 | be more common (and encouraged!). Note that this variable has no effect |
| 6700 | in Emacs since the necessary built-in functions don't exist (in Emacs |
| 6701 | 22.1 as of this writing in February 2007). |
| 6702 | |
| 6703 | Text properties are used to speed up skipping over syntactic whitespace, |
| 6704 | i.e. comments and preprocessor directives. Indenting a line after a |
| 6705 | huge macro definition can be slow the first time, but after that the |
| 6706 | text properties are in place and it should be fast (even after you've |
| 6707 | edited other parts of the file and then moved back). |
| 6708 | |
| 6709 | Font locking can be a CPU hog, especially the font locking done on |
| 6710 | decoration level 3 which tries to be very accurate. Note that that |
| 6711 | level is designed to be used with a font lock support mode that only |
| 6712 | fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time |
| 6713 | Lock mode, so make sure you use one of them. Fontification of a whole |
| 6714 | buffer with some thousand lines can often take over a minute. That is |
| 6715 | a known weakness; the idea is that it never should happen. |
| 6716 | |
| 6717 | The most effective way to speed up font locking is to reduce the |
| 6718 | decoration level to 2 by setting @code{font-lock-maximum-decoration} |
| 6719 | appropriately. That level is designed to be as pretty as possible |
| 6720 | without sacrificing performance. @xref{Font Locking Preliminaries}, for |
| 6721 | more info. |
| 6722 | |
| 6723 | |
| 6724 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6725 | @node Limitations and Known Bugs, FAQ, Performance Issues, Top |
| 6726 | @comment node-name, next, previous, up |
| 6727 | @chapter Limitations and Known Bugs |
| 6728 | @cindex limitations |
| 6729 | @cindex bugs |
| 6730 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6731 | |
| 6732 | @itemize @bullet |
| 6733 | @item |
| 6734 | @ccmode{} doesn't support trigraphs. (These are character sequences |
| 6735 | such as @samp{??(}, which represents @samp{[}. They date from a time |
| 6736 | when some character sets didn't have all the characters that C needs, |
| 6737 | and are now utterly obsolete.) |
| 6738 | |
| 6739 | @item |
| 6740 | There is no way to apply auto newline settings (@pxref{Auto-newlines}) |
| 6741 | on already typed lines. That's only a feature to ease interactive |
| 6742 | editing. |
| 6743 | |
| 6744 | To generalize this issue a bit: @ccmode{} is not intended to be used as |
| 6745 | a reformatter for old code in some more or less batch-like way. With |
| 6746 | the exception of some functions like @code{c-indent-region}, it's only |
| 6747 | geared to be used interactively to edit new code. There's currently no |
| 6748 | intention to change this goal. |
| 6749 | |
| 6750 | If you want to reformat old code, you're probably better off using some |
| 6751 | other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' |
| 6752 | Manual}, which has more powerful reformatting capabilities than |
| 6753 | @ccmode{}. |
| 6754 | |
| 6755 | @item |
| 6756 | The support for C++ templates (in angle brackets) is not yet complete. |
| 6757 | When a non-nested template is used in a declaration, @ccmode{} indents |
| 6758 | it and font-locks it OK. Templates used in expressions, and nested |
| 6759 | templates do not fare so well. Sometimes a workaround is to refontify |
| 6760 | the expression after typing the closing @samp{>}. |
| 6761 | |
| 6762 | @item |
| 6763 | On loading @ccmode{}, sometimes this error message appears: |
| 6764 | |
| 6765 | @example |
| 6766 | File mode specification error: (void-variable c-font-lock-keywords-3) |
| 6767 | @end example |
| 6768 | |
| 6769 | This is due to a bug in the function @code{eval-after-load} in some |
| 6770 | versions of (X)Emacs. It can manifest itself when there is a symbolic |
| 6771 | link in the path of the directory which contains (X)Emacs. As a |
| 6772 | workaround, put the following into your @file{.emacs} file, fairly |
| 6773 | early on: |
| 6774 | |
| 6775 | @example |
| 6776 | (defun my-load-cc-fonts () |
| 6777 | (require "cc-fonts")) |
| 6778 | (add-hook 'c-initialization-hook 'my-load-cc-fonts) |
| 6779 | @end example |
| 6780 | @end itemize |
| 6781 | |
| 6782 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6783 | @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top |
| 6784 | @comment node-name, next, previous, up |
| 6785 | @appendix Frequently Asked Questions |
| 6786 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6787 | |
| 6788 | @itemize @bullet |
| 6789 | @item |
| 6790 | @emph{How can I change the indent level from 4 spaces to 2 spaces?} |
| 6791 | |
| 6792 | Set the variable @code{c-basic-offset}. @xref{Getting Started}. |
| 6793 | |
| 6794 | @item |
| 6795 | @kindex RET |
| 6796 | @kindex C-j |
| 6797 | @emph{Why doesn't the @kbd{RET} key indent the new line?} |
| 6798 | |
| 6799 | Emacs' convention is that @kbd{RET} just adds a newline, and that |
| 6800 | @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this |
| 6801 | too by adding this to your @code{c-initialization-hook}: |
| 6802 | |
| 6803 | @example |
| 6804 | (define-key c-mode-base-map "\C-m" 'c-context-line-break) |
| 6805 | @end example |
| 6806 | |
| 6807 | @xref{Getting Started}. This is a very common question. If you want |
| 6808 | this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} |
| 6809 | |
| 6810 | @item |
| 6811 | @emph{How do I stop my code jumping all over the place when I type?} |
| 6812 | |
| 6813 | Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting |
| 6814 | Started}. |
| 6815 | |
| 6816 | @item |
| 6817 | @kindex C-x h |
| 6818 | @kindex C-M-\ |
| 6819 | @emph{How do I reindent the whole file?} |
| 6820 | |
| 6821 | Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit |
| 6822 | @kbd{C-M-\}. @xref{Indentation Commands}. |
| 6823 | |
| 6824 | @item |
| 6825 | @kindex C-M-q |
| 6826 | @kindex C-M-u |
| 6827 | @emph{How do I reindent the current block?} |
| 6828 | |
| 6829 | First move to the brace which opens the block with @kbd{C-M-u}, then |
| 6830 | reindent that expression with @kbd{C-M-q}. @xref{Indentation |
| 6831 | Commands}. |
| 6832 | |
| 6833 | @item |
| 6834 | @emph{I put @code{(c-set-offset 'substatement-open 0)} in my |
| 6835 | @file{.emacs} file but I get an error saying that @code{c-set-offset}'s |
| 6836 | function definition is void. What's wrong?} |
| 6837 | |
| 6838 | This means that @ccmode{} hasn't yet been loaded into your Emacs |
| 6839 | session by the time the @code{c-set-offset} call is reached, most |
| 6840 | likely because @ccmode{} is being autoloaded. Instead of putting the |
| 6841 | @code{c-set-offset} line in your top-level @file{.emacs} file, put it |
| 6842 | in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply |
| 6843 | modify @code{c-offsets-alist} directly: |
| 6844 | |
| 6845 | @example |
| 6846 | (setq c-offsets-alist '((substatement-open . 0))) |
| 6847 | @end example |
| 6848 | |
| 6849 | @item |
| 6850 | @cindex open paren in column zero |
| 6851 | @emph{I have an open paren character at column zero inside a comment or |
| 6852 | multiline string literal, and it causes the fontification and/or |
| 6853 | indentation to go haywire. What gives?} |
| 6854 | |
| 6855 | It's due to the ad-hoc rule in (X)Emacs that such open parens always |
| 6856 | start defuns (which translates to functions, classes, namespaces or any |
| 6857 | other top-level block constructs in the @ccmode{} languages). |
| 6858 | @ifset XEMACS |
| 6859 | @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. |
| 6860 | @end ifset |
| 6861 | @ifclear XEMACS |
| 6862 | @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details |
| 6863 | (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). |
| 6864 | @end ifclear |
| 6865 | |
| 6866 | This heuristic is built into the core syntax analysis routines in |
| 6867 | (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs |
| 6868 | 21.1 it became possible to turn it off@footnote{Using the variable |
| 6869 | @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so |
| 6870 | there since it's got its own system to keep track of blocks. |
| 6871 | |
| 6872 | @end itemize |
| 6873 | |
| 6874 | |
| 6875 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6876 | @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top |
| 6877 | @comment node-name, next, previous, up |
| 6878 | @appendix Getting the Latest CC Mode Release |
| 6879 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6880 | |
| 6881 | @ccmode{} has been standard with all versions of Emacs since 19.34 and |
| 6882 | of XEmacs since 19.16. |
| 6883 | |
| 6884 | @cindex web site |
| 6885 | Due to release schedule skew, it is likely that all of these Emacsen |
| 6886 | have old versions of @ccmode{} and so should be upgraded. Access to the |
| 6887 | @ccmode{} source code, as well as more detailed information on Emacsen |
| 6888 | compatibility, etc. are all available on the web site: |
| 6889 | |
| 6890 | @quotation |
| 6891 | @uref{http://cc-mode.sourceforge.net/} |
| 6892 | @end quotation |
| 6893 | |
| 6894 | |
| 6895 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6896 | @node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top |
| 6897 | @comment node-name, next, previous, up |
| 6898 | @appendix Mailing Lists and Submitting Bug Reports |
| 6899 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6900 | |
| 6901 | @kindex C-c C-b |
| 6902 | @findex c-submit-bug-report |
| 6903 | @findex submit-bug-report (c-) |
| 6904 | To report bugs, use the @kbd{C-c C-b} (bound to |
| 6905 | @code{c-submit-bug-report}) command. This provides vital information |
| 6906 | we need to reproduce your problem. Make sure you include a concise, |
| 6907 | but complete code example. Please try to boil your example down to |
| 6908 | just the essential code needed to reproduce the problem, and include |
| 6909 | an exact recipe of steps needed to expose the bug. Be especially sure |
| 6910 | to include any code that appears @emph{before} your bug example, if |
| 6911 | you think it might affect our ability to reproduce it. |
| 6912 | |
| 6913 | Please try to produce the problem in an Emacs instance without any |
| 6914 | customizations loaded (i.e. start it with the @samp{-q --no-site-file} |
| 6915 | arguments). If it works correctly there, the problem might be caused |
| 6916 | by faulty customizations in either your own or your site |
| 6917 | configuration. In that case, we'd appreciate it if you isolate the |
| 6918 | Emacs Lisp code that triggers the bug and include it in your report. |
| 6919 | |
| 6920 | @cindex bug report mailing list |
| 6921 | Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can |
| 6922 | also send other questions and suggestions (kudos? @t{;-)} to that |
| 6923 | address. It's a mailing list which you can join or browse an archive |
| 6924 | of; see the web site at @uref{http://cc-mode.sourceforge.net/} for |
| 6925 | further details. |
| 6926 | |
| 6927 | @cindex announcement mailing list |
| 6928 | If you want to get announcements of new @ccmode{} releases, send the |
| 6929 | word @emph{subscribe} in the body of a message to |
| 6930 | @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible |
| 6931 | to subscribe from the web site too. Announcements will also be posted |
| 6932 | to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, |
| 6933 | @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, |
| 6934 | @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, |
| 6935 | @code{comp.lang.idl}, and @code{comp.lang.awk}. |
| 6936 | @c There is no newsgroup for Pike. :-( |
| 6937 | |
| 6938 | |
| 6939 | @node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top |
| 6940 | @appendix GNU Free Documentation License |
| 6941 | @include doclicense.texi |
| 6942 | |
| 6943 | |
| 6944 | @c Removed the tentative node "Mode Initialization" from here, 2005/8/27. |
| 6945 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6946 | @node Command and Function Index, Variable Index, GNU Free Documentation License, Top |
| 6947 | @comment node-name, next, previous, up |
| 6948 | @unnumbered Command and Function Index |
| 6949 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6950 | |
| 6951 | Since most @ccmode{} commands are prepended with the string |
| 6952 | @samp{c-}, each appears under its @code{c-@var{thing}} name and its |
| 6953 | @code{@var{thing} (c-)} name. |
| 6954 | @iftex |
| 6955 | @sp 2 |
| 6956 | @end iftex |
| 6957 | @printindex fn |
| 6958 | |
| 6959 | |
| 6960 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6961 | @node Variable Index, Concept and Key Index, Command and Function Index, Top |
| 6962 | @comment node-name, next, previous, up |
| 6963 | @unnumbered Variable Index |
| 6964 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6965 | |
| 6966 | Since most @ccmode{} variables are prepended with the string |
| 6967 | @samp{c-}, each appears under its @code{c-@var{thing}} name and its |
| 6968 | @code{@var{thing} (c-)} name. |
| 6969 | @iftex |
| 6970 | @sp 2 |
| 6971 | @end iftex |
| 6972 | @printindex vr |
| 6973 | |
| 6974 | |
| 6975 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6976 | @node Concept and Key Index, , Variable Index, Top |
| 6977 | @comment node-name, next, previous, up |
| 6978 | @unnumbered Concept and Key Index |
| 6979 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6980 | |
| 6981 | @printindex cp |
| 6982 | |
| 6983 | |
| 6984 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6985 | @comment Epilogue. |
| 6986 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
| 6987 | |
| 6988 | @iftex |
| 6989 | @page |
| 6990 | @summarycontents |
| 6991 | @contents |
| 6992 | @end iftex |
| 6993 | |
| 6994 | @bye |
| 6995 | |
| 6996 | @ignore |
| 6997 | arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 |
| 6998 | @end ignore |