1This is ccmode.info, produced by makeinfo version 6.7 from cc-mode.texi. 2 3This manual is for CC Mode in Emacs. 4 5 Copyright © 1995–2021 Free Software Foundation, Inc. 6 7 Permission is granted to copy, distribute and/or modify this 8 document under the terms of the GNU Free Documentation License, 9 Version 1.3 or any later version published by the Free Software 10 Foundation; with no Invariant Sections, with the Front-Cover Texts 11 being “A GNU Manual”, and with the Back-Cover Texts as in (a) 12 below. A copy of the license is included in the section entitled 13 “GNU Free Documentation License”. 14 15 (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and 16 modify this GNU manual.” 17INFO-DIR-SECTION Emacs editing modes 18START-INFO-DIR-ENTRY 19* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, 20 Java, Pike, AWK, and CORBA IDL code. 21END-INFO-DIR-ENTRY 22 23 24File: ccmode.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 25 26CC Mode 27******* 28 29CC Mode is a GNU Emacs mode for editing files containing C, C++, 30Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike and 31AWK code. It provides syntax-based indentation, font locking, and has 32several handy commands and some minor modes to make the editing easier. 33It does not provide tools to look up and navigate between functions, 34classes, etc.; there are other packages for that. 35 36 This manual is for CC Mode in Emacs. 37 38 Copyright © 1995–2021 Free Software Foundation, Inc. 39 40 Permission is granted to copy, distribute and/or modify this 41 document under the terms of the GNU Free Documentation License, 42 Version 1.3 or any later version published by the Free Software 43 Foundation; with no Invariant Sections, with the Front-Cover Texts 44 being “A GNU Manual”, and with the Back-Cover Texts as in (a) 45 below. A copy of the license is included in the section entitled 46 “GNU Free Documentation License”. 47 48 (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and 49 modify this GNU manual.” 50 51* Menu: 52 53* Introduction:: 54* Overview:: 55* Getting Started:: 56* Commands:: 57* Font Locking:: 58* Config Basics:: 59* Custom Filling and Breaking:: 60* Custom Auto-newlines:: 61* Clean-ups:: 62* Indentation Engine Basics:: 63* Customizing Indentation:: 64* Custom Macros:: 65* Odds and Ends:: 66* Sample Init File:: 67* Performance Issues:: 68* Limitations and Known Bugs:: 69* FAQ:: 70* Updating CC Mode:: 71* Mailing Lists and Bug Reports:: 72* GNU Free Documentation License:: 73* Command and Function Index:: 74* Variable Index:: 75* Concept and Key Index:: 76 77 — The Detailed Node Listing — 78 79Commands 80 81* Indentation Commands:: 82* Comment Commands:: 83* Movement Commands:: 84* Filling and Breaking:: 85* Minor Modes:: 86* Electric Keys:: 87* Auto-newlines:: 88* Hungry WS Deletion:: 89* Subword Movement:: 90* Other Commands:: 91 92Font Locking 93 94* Font Locking Preliminaries:: 95* Faces:: 96* Doc Comments:: 97* Misc Font Locking:: 98* AWK Mode Font Locking:: 99 100Configuration Basics 101 102* CC Hooks:: 103* Style Variables:: 104* Styles:: 105 106Styles 107 108* Built-in Styles:: 109* Choosing a Style:: 110* Adding Styles:: 111* Guessing the Style:: 112* File Styles:: 113 114Customizing Auto-newlines 115 116* Hanging Braces:: 117* Hanging Colons:: 118* Hanging Semicolons and Commas:: 119 120Hanging Braces 121 122* Custom Braces:: 123 124Indentation Engine Basics 125 126* Syntactic Analysis:: 127* Syntactic Symbols:: 128* Indentation Calculation:: 129 130Syntactic Symbols 131 132* Function Symbols:: 133* Class Symbols:: 134* Conditional Construct Symbols:: 135* Switch Statement Symbols:: 136* Brace List Symbols:: 137* External Scope Symbols:: 138* Paren List Symbols:: 139* Literal Symbols:: 140* Multiline Macro Symbols:: 141* Objective-C Method Symbols:: 142* Java Symbols:: 143* Statement Block Symbols:: 144* K&R Symbols:: 145 146Customizing Indentation 147 148* c-offsets-alist:: 149* Interactive Customization:: 150* Line-Up Functions:: 151* Custom Line-Up:: 152* Other Indentation:: 153 154Line-Up Functions 155 156* Brace/Paren Line-Up:: 157* List Line-Up:: 158* Operator Line-Up:: 159* Comment Line-Up:: 160* Misc Line-Up:: 161 162 163Customizing Macros 164 165* Macro Backslashes:: 166* Macros with ;:: 167* Noise Macros:: 168 169 170 171File: ccmode.info, Node: Introduction, Next: Overview, Prev: Top, Up: Top 172 1731 Introduction 174************** 175 176Welcome to CC Mode, a GNU Emacs mode for editing files containing C, 177C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and 178CIDL), Pike and AWK code. This incarnation of the mode is descended 179from ‘c-mode.el’ (also called “Boring Old C Mode” or BOCM :-), 180‘c++-mode.el’ version 2, which Barry Warsaw had been maintaining since 1811992, and ‘awk-mode.el’, a long neglected mode in the (X)Emacs base. 182 183 Late in 1997, Martin Stjernholm joined Barry on the CC Mode 184Maintainers Team, and implemented the Pike support. In 2000 Martin took 185over as the sole maintainer. In 2001 Alan Mackenzie joined the team, 186implementing AWK support in version 5.30. CC Mode did not originally 187contain the font lock support for its languages; that was added in 188version 5.30. 189 190 This manual describes CC Mode version 5.34. 191 192 CC Mode supports the editing of C, C++, Objective-C, Java, CORBA’s 193Interface Definition Language, Pike(1) and AWK files. In this way, you 194can easily set up consistent font locking and coding styles for use in 195editing all of these languages, although AWK is not yet as uniformly 196integrated as the other languages. 197 198 Note that the name of this package is “CC Mode”, but there is no top 199level ‘cc-mode’ entry point. All of the variables, commands, and 200functions in CC Mode are prefixed with ‘c-THING’, and ‘c-mode’, 201‘c++-mode’, ‘objc-mode’, ‘java-mode’, ‘idl-mode’, ‘pike-mode’, and 202‘awk-mode’ entry points are provided. This package is intended to be a 203replacement for ‘c-mode.el’, ‘c++-mode.el’ and ‘awk-mode.el’. 204 205 A special word of thanks goes to Krishna Padmasola for his work in 206converting the original ‘README’ file to Texinfo format. I’d also like 207to thank all the CC Mode victims who help enormously during the early 208beta stages of CC Mode’s development. 209 210 ---------- Footnotes ---------- 211 212 (1) A C-like scripting language with its roots in the LPC language 213used in some MUD engines. See <https://pike.lysator.liu.se/>. 214 215 216File: ccmode.info, Node: Overview, Next: Getting Started, Prev: Introduction, Up: Top 217 2182 Overview of the Manual 219************************ 220 221The manual starts with several introductory chapters (including this 222one). 223 224The next chunk of the manual describes the day to day _use_ of CC Mode 225(as contrasted with how to customize it). 226 227 • The chapter “Commands” describes in detail how to use (nearly) all 228 of CC Mode’s features. There are extensive cross-references from 229 here to the corresponding sections later in the manual which tell 230 you how to customize these features. 231 232 • “Font Locking” describes how “syntax highlighting” is applied to 233 your buffers. It is mainly background information and can be 234 skipped over at a first reading. 235 236The next chunk of the manual describes how to _customize_ CC Mode. 237Typically, an overview of a topic is given at the chapter level, then 238the sections and subsections describe the material in increasing detail. 239 240 • The chapter “Configuration Basics” tells you _how_ to write 241 customizations: whether in hooks, in styles, in both, or in 242 neither, depending on your needs. It describes the CC Mode style 243 system and lists the standard styles that CC Mode supplies. 244 245 • The next few chapters describe in detail how to customize the 246 various features of CC Mode. 247 248 • Finally, there is a sample ‘.emacs’ fragment, which might help you 249 in creating your own customization. 250 251The manual ends with “this and that”, things that don’t fit cleanly into 252any of the previous chunks. 253 254 • Two chapters discuss the performance of CC Mode and known 255 bugs/limitations. 256 257 • The FAQ contains a list of common problems and questions. 258 259 • The next two chapters tell you how to get in touch with the CC Mode 260 project: whether for updating CC Mode or submitting bug reports. 261 262Finally, there are the customary indices. 263 264 265File: ccmode.info, Node: Getting Started, Next: Commands, Prev: Overview, Up: Top 266 2673 Getting Started 268***************** 269 270If you got this version of CC Mode with Emacs or XEmacs, it should work 271just fine right out of the box. Note however that you might not have 272the latest CC Mode release and might want to upgrade your copy (see 273below). 274 275 You should probably start by skimming through the entire Commands 276chapter (*note Commands::) to get an overview of CC Mode’s capabilities. 277 278 After trying out some commands, you may dislike some aspects of CC 279Mode’s default configuration. Here is an outline of how to change some 280of the settings that newcomers to CC Mode most often want to change: 281 282c-basic-offset 283 This Lisp variable holds an integer, the number of columns CC Mode 284 indents nested code. To set this value to 6, customize 285 ‘c-basic-offset’ or put this into your ‘.emacs’: 286 287 (setq c-basic-offset 6) 288 289The (indentation) style 290 The basic “shape” of indentation created by CC Mode—by default, 291 this is ‘gnu’ style (except for Java and AWK buffers). A list of 292 the available styles and their descriptions can be found in *note 293 Built-in Styles::. A complete specification of the CC Mode style 294 system, including how to create your own style, can be found in the 295 chapter *note Styles::. To set your style to ‘linux’, either 296 customize ‘c-default-style’ or put this into your ‘.emacs’: 297 298 (setq c-default-style '((java-mode . "java") 299 (awk-mode . "awk") 300 (other . "linux"))) 301 302Electric Indentation 303 Normally, when you type “punctuation” characters such as ‘;’ or 304 ‘{’, CC Mode instantly reindents the current line. This can be 305 disconcerting until you get used to it. To disable “electric 306 indentation” in the current buffer, type ‘C-c C-l’. Type the same 307 thing to enable it again. To have electric indentation disabled by 308 default, put the following into your ‘.emacs’ file(1): 309 310 (setq-default c-electric-flag nil) 311 312 Details of this and other similar “Minor Modes” appear in the 313 section *note Minor Modes::. 314 315Making the <RET> key indent the new line 316 The standard Emacs binding for <RET> just adds a new line. If you 317 want it to reindent the new line as well, rebind the key. Note 318 that the action of rebinding would fail if the pertinent keymap 319 didn’t yet exist—we thus need to delay the action until after CC 320 Mode has been loaded. Put the following code into your ‘.emacs’: 321 322 (defun my-make-CR-do-indent () 323 (define-key c-mode-base-map "\C-m" 'c-context-line-break)) 324 (add-hook 'c-initialization-hook 'my-make-CR-do-indent) 325 326 This example demonstrates the use of a very powerful CC Mode (and 327 Emacs) facility, the hook. The use of CC Mode’s hooks is described 328 in *note CC Hooks::. 329 330 All these settings should occur in your ‘.emacs’ _before_ any CC Mode 331buffers get loaded—in particular, before any call of ‘desktop-read’. 332 333 As you get to know the mode better, you may want to make more 334ambitious changes to your configuration. For this, you should start 335reading the chapter *note Config Basics::. 336 337 If you are upgrading an existing CC Mode installation, please see the 338‘README’ file for installation details. In particular, if you are going 339to be editing AWK files, ‘README’ describes how to configure your 340(X)Emacs so that CC Mode will supersede the obsolete ‘awk-mode.el’ which 341might have been supplied with your (X)Emacs. CC Mode might not work 342with older versions of Emacs or XEmacs. See the CC Mode release notes 343at <http://cc-mode.sourceforge.net> for the latest information on Emacs 344version and package compatibility (*note Updating CC Mode::). 345 346 -- Command: c-version 347 You can find out what version of CC Mode you are using by visiting 348 a C file and entering ‘M-x c-version <RET>’. You should see this 349 message in the echo area: 350 351 Using CC Mode version 5.XX 352 353 where ‘XX’ is the minor release number. 354 355 ---------- Footnotes ---------- 356 357 (1) There is no “easy customization” facility for making this change. 358 359 360File: ccmode.info, Node: Commands, Next: Font Locking, Prev: Getting Started, Up: Top 361 3624 Commands 363********** 364 365This chapter specifies all of CC Mode’s commands, and thus contains 366nearly everything you need to know to _use_ CC Mode (as contrasted with 367configuring it). “Commands” here means both control key sequences and 368“electric keys”, these being characters such as ‘;’ which, as well as 369inserting themselves into the buffer, also do other things. 370 371 You might well want to review *note (emacs)Moving by Parens::, which 372describes commands for moving around brace and parenthesis structures. 373 374* Menu: 375 376* Indentation Commands:: 377* Comment Commands:: 378* Movement Commands:: 379* Filling and Breaking:: 380* Minor Modes:: 381* Electric Keys:: 382* Auto-newlines:: 383* Hungry WS Deletion:: 384* Subword Movement:: 385* Other Commands:: 386 387 388File: ccmode.info, Node: Indentation Commands, Next: Comment Commands, Prev: Commands, Up: Commands 389 3904.1 Indentation Commands 391======================== 392 393The following commands reindent C constructs. Note that when you change 394your coding style, either interactively or through some other means, 395your file does _not_ automatically get reindented. You will need to 396execute one of the following commands to see the effects of your 397changes. 398 399 Also, variables like ‘c-hanging-*’ and ‘c-cleanup-list’ (*note Custom 400Auto-newlines::) only affect how on-the-fly code is formatted. Changing 401the “hanginess” of a brace and then reindenting, will not move the brace 402to a different line. For this, you’re better off getting an external 403program like GNU ‘indent’, which will rearrange brace location, amongst 404other things. 405 406 Preprocessor directives are handled as syntactic whitespace from 407other code, i.e., they can be interspersed anywhere without affecting 408the indentation of the surrounding code, just like comments. 409 410 The code inside macro definitions is, by default, still analyzed 411syntactically so that you get relative indentation there just as you’d 412get if the same code was outside a macro. However, since there is no 413hint about the syntactic context, i.e., whether the macro expands to an 414expression, to some statements, or perhaps to whole functions, the 415syntactic recognition can be wrong. CC Mode manages to figure it out 416correctly most of the time, though. 417 418 Some macros, when invoked, “have their own semicolon”. To get the 419next line indented correctly, rather than as a continuation line, *Note 420Macros with ;::. 421 422 Reindenting large sections of code can take a long time. When CC 423Mode reindents a region of code, it is essentially equivalent to hitting 424<TAB> on every line of the region. 425 426 These commands indent code: 427 428‘<TAB>’ (‘c-indent-command’) 429 This command indents the current line. That is all you need to 430 know about it for normal use. 431 432 ‘c-indent-command’ does different things, depending on the setting 433 of ‘c-syntactic-indentation’ (*note Indentation Engine Basics::): 434 435 • When it’s non-‘nil’ (which it normally is), the command 436 indents the line according to its syntactic context. With a 437 prefix argument (‘C-u <TAB>’), it will re-indent the entire 438 expression(1) that begins at the line’s left margin. 439 440 • When it’s ‘nil’, the command indents the line by an extra 441 ‘c-basic-offset’ columns. A prefix argument acts as a 442 multiplier. A bare prefix (‘C-u <TAB>’) is equivalent to −1, 443 removing ‘c-basic-offset’ columns from the indentation. 444 445 The precise behavior is modified by several variables: With 446 ‘c-tab-always-indent’, you can make <TAB> insert whitespace in some 447 circumstances—‘c-insert-tab-function’ then defines precisely what 448 sort of “whitespace” this will be. Set the standard Emacs variable 449 ‘indent-tabs-mode’ to ‘t’ if you want real ‘tab’ characters to be 450 used in the indentation, to ‘nil’ if you want only spaces. *Note 451 (emacs)Just Spaces::. 452 453 -- User Option: c-tab-always-indent 454 This variable modifies how <TAB> operates. 455 • When it is ‘t’ (the default), <TAB> simply indents the 456 current line. 457 • When it is ‘nil’, <TAB> (re)indents the line only if 458 point is to the left of the first non-whitespace 459 character on the line. Otherwise it inserts some 460 whitespace (a tab or an equivalent number of spaces; see 461 below) at point. 462 • With some other value, the line is reindented. 463 Additionally, if point is within a string or comment, 464 some whitespace is inserted. 465 466 -- User Option: c-insert-tab-function 467 When “some whitespace” is inserted as described above, what 468 actually happens is that the function stored in 469 ‘c-insert-tab-function’ is called. Normally, this is 470 ‘insert-tab’, which inserts a real tab character or the 471 equivalent number of spaces (depending on ‘indent-tabs-mode’). 472 Some people, however, set ‘c-insert-tab-function’ to 473 ‘tab-to-tab-stop’ so as to get hard tab stops when indenting. 474 475The kind of indentation the next five commands do depends on the setting 476of ‘c-syntactic-indentation’ (*note Indentation Engine Basics::): 477 • when it is non-‘nil’ (the default), the commands indent lines 478 according to their syntactic context; 479 • when it is ‘nil’, they just indent each line the same amount as the 480 previous non-blank line. The commands that indent a region aren’t 481 very useful in this case. 482 483‘C-M-q’ (‘c-indent-exp’) 484 Indents an entire balanced brace or parenthesis expression. Note 485 that point must be on the opening brace or parenthesis of the 486 expression you want to indent. 487 488‘C-c C-q’ (‘c-indent-defun’) 489 Indents the entire top-level function, class or macro definition 490 encompassing point. It leaves point unchanged. This function 491 can’t be used to reindent a nested brace construct, such as a 492 nested class or function, or a Java method. The top-level 493 construct being reindented must be complete, i.e., it must have 494 both a beginning brace and an ending brace. 495 496‘C-M-\’ (‘indent-region’) 497 Indents an arbitrary region of code. This is a standard Emacs 498 command, tailored for C code in a CC Mode buffer. Note, of course, 499 that point and mark must delineate the region you want to indent. 500 501‘C-M-h’ (‘c-mark-function’) 502 While not strictly an indentation command, this is useful for 503 marking the current top-level function or class definition as the 504 current region. As with ‘c-indent-defun’, this command operates on 505 top-level constructs, and can’t be used to mark say, a Java method. 506 507 These variables are also useful when indenting code: 508 509 -- User Option: indent-tabs-mode 510 This is a standard Emacs variable that controls how line 511 indentation is composed. When it’s non-‘nil’, tabs can be used in 512 a line’s indentation, otherwise only spaces are used. 513 514 -- User Option: c-progress-interval 515 When indenting large regions of code, this variable controls how 516 often a progress message is displayed. Set this variable to ‘nil’ 517 to inhibit the progress messages, or set it to an integer which is 518 how often (in seconds) progress messages are to be displayed. 519 520 ---------- Footnotes ---------- 521 522 (1) this is only useful for a line starting with a comment opener or 523an opening brace, parenthesis, or string quote. 524 525 526File: ccmode.info, Node: Comment Commands, Next: Movement Commands, Prev: Indentation Commands, Up: Commands 527 5284.2 Comment Commands 529==================== 530 531When the commands in this section add comment delimiters, they use 532either line comments or block comments depending on the setting of the 533comment style (*note Minor Modes::). 534 535‘C-c C-c’ (‘comment-region’) 536 This command comments out the lines that start in the region. With 537 a negative argument, it does the opposite: it deletes the comment 538 delimiters from these lines. *Note (emacs)Multi-Line Comments::, 539 for fuller details. ‘comment-region’ isn’t actually part of CC 540 Mode; it is given a CC Mode binding for convenience. 541 542‘M-;’ (‘comment-dwim’ or ‘indent-for-comment’ (1)) 543 Insert a comment at the end of the current line, if none is there 544 already. Then reindent the comment according to ‘comment-column’ 545 (*note (emacs)Options for Comments::) and the variables below. 546 Finally, position the point after the comment starter. ‘C-u M-;’ 547 kills any comment on the current line, together with any whitespace 548 before it. This is a standard Emacs command, but CC Mode enhances 549 it a bit with two variables: 550 551 -- User Option: c-indent-comment-alist 552 This style variable allows you to vary the column that ‘M-;’ 553 puts the comment at, depending on what sort of code is on the 554 line, and possibly the indentation of any similar comment on 555 the preceding line. It is an association list that maps 556 different types of lines to actions describing how they should 557 be handled. If a certain line type isn’t present on the list 558 then the line is indented to the column specified by 559 ‘comment-column’. 560 561 See the documentation string for a full description of this 562 variable (use ‘C-h v c-indent-comment-alist’). 563 564 -- User Option: c-indent-comments-syntactically-p 565 Normally, when this style variable is ‘nil’, ‘M-;’ will indent 566 comment-only lines according to ‘c-indent-comment-alist’, just 567 as it does with lines where other code precede the comments. 568 However, if you want it to act just like <TAB> for 569 comment-only lines you can get that by setting 570 ‘c-indent-comments-syntactically-p’ to non-‘nil’. 571 572 If ‘c-indent-comments-syntactically-p’ is non-‘nil’ then 573 ‘c-indent-comment-alist’ won’t be consulted at all for 574 comment-only lines. 575 576 ---------- Footnotes ---------- 577 578 (1) The name of this command varies between (X)Emacs versions. 579 580 581File: ccmode.info, Node: Movement Commands, Next: Filling and Breaking, Prev: Comment Commands, Up: Commands 582 5834.3 Movement Commands 584===================== 585 586CC Mode contains some useful commands for moving around in C code. 587 588‘C-M-a’ (‘c-beginning-of-defun’) 589‘C-M-e’ (‘c-end-of-defun’) 590 591 Move to the beginning or end of the current or next function. 592 Other constructs (such as a structs or classes) which have a brace 593 block also count as “functions” here. To move over several 594 functions, you can give these commands a repeat count. 595 596 The start of a function is at its header. The end of the function 597 is after its closing brace, or after the semicolon of a construct 598 (such as a ‘struct’) which doesn’t end at the brace. These two 599 commands try to leave point at the beginning of a line near the 600 actual start or end of the function. This occasionally causes 601 point not to move at all. 602 603 By default, these commands will recognize functions contained 604 within a “declaration scope” such as a C++ ‘class’ or ‘namespace’ 605 construct, should the point start inside it. If CC Mode fails to 606 find function beginnings or ends inside the current declaration 607 scope, it will search the enclosing scopes. If you want CC Mode to 608 recognize functions only at the top level(1), set ‘c-defun-tactic’ 609 to ‘t’. 610 611 These functions are analogous to the Emacs built-in commands 612 ‘beginning-of-defun’ and ‘end-of-defun’, except they eliminate the 613 constraint that the top-level opening brace of the defun must be in 614 column zero. See *note (emacs)Defuns::, for more information. 615 616‘C-M-a’ (AWK Mode) (‘c-awk-beginning-of-defun’) 617‘C-M-e’ (AWK Mode) (‘c-awk-end-of-defun’) 618 Move to the beginning or end of the current or next AWK defun. 619 These commands can take prefix-arguments, their functionality being 620 entirely equivalent to ‘beginning-of-defun’ and ‘end-of-defun’. 621 622 AWK Mode “defuns” are either pattern/action pairs (either of which 623 might be implicit) or user defined functions. Having the ‘{’ and 624 ‘}’ (if there are any) in column zero, as is suggested for some 625 modes, is neither necessary nor helpful in AWK mode. 626 627‘M-a’ (‘c-beginning-of-statement’) 628‘M-e’ (‘c-end-of-statement’) 629 Move to the beginning or end of the innermost C statement. If 630 point is already there, move to the next beginning or end of a 631 statement, even if that means moving into a block. (Use ‘C-M-b’ or 632 ‘C-M-f’ to move over a balanced block.) A prefix argument N means 633 move over N statements. 634 635 If point is within or next to a comment or a string which spans 636 more than one line, these commands move by sentences instead of 637 statements. 638 639 When called from a program, these functions take three optional 640 arguments: the repetition count, a buffer position limit which is 641 the farthest back to search for the syntactic context, and a flag 642 saying whether to do sentence motion in or near comments and 643 multiline strings. 644 645‘C-c C-u’ (‘c-up-conditional’) 646 Move back to the containing preprocessor conditional, leaving the 647 mark behind. A prefix argument acts as a repeat count. With a 648 negative argument, move forward to the end of the containing 649 preprocessor conditional. 650 651 ‘#elif’ is treated like ‘#else’ followed by ‘#if’, so the function 652 stops at them when going backward, but not when going forward. 653 654 This key sequence is not bound in AWK Mode, which doesn’t have 655 preprocessor statements. 656 657‘M-x c-up-conditional-with-else’ 658 A variety of ‘c-up-conditional’ that also stops at ‘#else’ lines. 659 Normally those lines are ignored. 660 661‘M-x c-down-conditional’ 662 Move forward into the next nested preprocessor conditional, leaving 663 the mark behind. A prefix argument acts as a repeat count. With a 664 negative argument, move backward into the previous nested 665 preprocessor conditional. 666 667 ‘#elif’ is treated like ‘#else’ followed by ‘#if’, so the function 668 stops at them when going forward, but not when going backward. 669 670‘M-x c-down-conditional-with-else’ 671 A variety of ‘c-down-conditional’ that also stops at ‘#else’ lines. 672 Normally those lines are ignored. 673 674‘C-c C-p’ (‘c-backward-conditional’) 675‘C-c C-n’ (‘c-forward-conditional’) 676 Move backward or forward across a preprocessor conditional, leaving 677 the mark behind. A prefix argument acts as a repeat count. With a 678 negative argument, move in the opposite direction. 679 680 These key sequences are not bound in AWK Mode, which doesn’t have 681 preprocessor statements. 682 683‘M-x c-backward-into-nomenclature’ 684‘M-x c-forward-into-nomenclature’ 685 A popular programming style, especially for object-oriented 686 languages such as C++ is to write symbols in a mixed case format, 687 where the first letter of each word is capitalized, and not 688 separated by underscores. E.g., 689 ‘SymbolsWithMixedCaseAndNoUnderlines’. 690 691 These commands move backward or forward to the beginning of the 692 next capitalized word. With prefix argument N, move N times. If N 693 is negative, move in the opposite direction. 694 695 Note that these two commands have been superseded by 696 ‘subword-mode’, which you should use instead. *Note Subword 697 Movement::. They might be removed from a future release of CC 698 Mode. 699 700 ---------- Footnotes ---------- 701 702 (1) this was CC Mode’s behavior prior to version 5.32. 703 704 705File: ccmode.info, Node: Filling and Breaking, Next: Minor Modes, Prev: Movement Commands, Up: Commands 706 7074.4 Filling and Line Breaking Commands 708====================================== 709 710Since there’s a lot of normal text in comments and string literals, CC 711Mode provides features to edit these like in text mode. The goal is to 712do it seamlessly, i.e., you can use auto fill mode, sentence and 713paragraph movement, paragraph filling, adaptive filling etc. wherever 714there’s a piece of normal text without having to think much about it. 715CC Mode keeps the indentation, fixes suitable comment line prefixes, and 716so on. 717 718 You can configure the exact way comments get filled and broken, and 719where Emacs does auto-filling (*note Custom Filling and Breaking::). 720Typically, the style system (*note Styles::) will have set this up for 721you, so you probably won’t have to bother. 722 723 Line breaks are by default handled (almost) the same regardless of 724whether they are made by auto fill mode (*note (emacs)Auto Fill::), by 725paragraph filling (e.g., with ‘M-q’), or explicitly with ‘M-j’ or 726similar methods. In string literals, the new line gets the same 727indentation as the previous nonempty line.(1). 728 729‘M-q’ (‘c-fill-paragraph’) 730 This command fills multiline string literals and both block and 731 line style comments. In Java buffers, the Javadoc markup words are 732 recognized as paragraph starters. The line oriented Pike autodoc 733 markup words are recognized in the same way in Pike mode. 734 735 The formatting of the starters (‘/*’) and enders (‘*/’) of block 736 comments are kept as they were before the filling. I.e., if either 737 the starter or ender were on a line of its own, then it stays on 738 its own line; conversely, if the delimiter has comment text on its 739 line, it keeps at least one word of that text with it on the line. 740 741 This command is the replacement for ‘fill-paragraph’ in CC Mode 742 buffers. 743 744‘M-j’ (‘c-indent-new-comment-line’) 745 This breaks the current line at point and indents the new line. If 746 point was in a comment, the new line gets the proper comment line 747 prefix. If point was inside a macro, a backslash is inserted 748 before the line break. It is the replacement for 749 ‘indent-new-comment-line’. 750 751‘M-x c-context-line-break’ 752 Insert a line break suitable to the context: If the point is inside 753 a comment, the new line gets the suitable indentation and comment 754 line prefix like ‘c-indent-new-comment-line’. In normal code it’s 755 indented like ‘newline-and-indent’ would do. In macros it acts 756 like ‘newline-and-indent’ but additionally inserts and optionally 757 aligns the line ending backslash so that the macro remains 758 unbroken. *Note Custom Macros::, for details about the backslash 759 alignment. In a string, a backslash is inserted only if the string 760 is within a macro(2). 761 762 This function is not bound to a key by default, but it’s intended 763 to be used on the ‘RET’ key. If you like the behavior of 764 ‘newline-and-indent’ on ‘RET’, you should consider switching to 765 this function. *Note Sample Init File::. 766 767‘M-x c-context-open-line’ 768 This is to ‘C-o’ (‘M-x open-line’) as ‘c-context-line-break’ is to 769 ‘RET’. I.e., it works just like ‘c-context-line-break’ but leaves 770 the point before the inserted line break. 771 772 ---------- Footnotes ---------- 773 774 (1) You can change this default by setting the ‘string’ syntactic 775symbol (*note Syntactic Symbols:: and *note Customizing Indentation::) 776 777 (2) In GCC, unescaped line breaks within strings are valid. 778 779 780File: ccmode.info, Node: Minor Modes, Next: Electric Keys, Prev: Filling and Breaking, Up: Commands 781 7824.5 Minor Modes 783=============== 784 785CC Mode contains several minor-mode-like features that you might find 786useful while writing new code or editing old code: 787 788comment style 789 This specifies whether comment commands (such as ‘M-;’) insert 790 block comments or line comments(1). 791electric mode 792 When this is enabled, certain visible characters cause reformatting 793 as they are typed. This is normally helpful, but can be a nuisance 794 when editing chaotically formatted code. It can also be 795 disconcerting, especially for users who are new to CC Mode. 796auto-newline mode 797 This automatically inserts newlines where you’d probably want to 798 type them yourself, e.g., after typing ‘}’s. Its action is 799 suppressed when electric mode is disabled. 800hungry-delete mode 801 This lets you delete a contiguous block of whitespace with a single 802 key: for example, the newline and indentation just inserted by 803 auto-newline when you want to back up and write a comment after the 804 last statement. 805subword mode 806 This mode makes basic word movement commands like ‘M-f’ 807 (‘forward-word’) and ‘M-b’ (‘backward-word’) treat the parts of 808 sillycapsed symbols as different words. E.g., ‘NSGraphicsContext’ 809 is treated as three words ‘NS’, ‘Graphics’, and ‘Context’. 810syntactic-indentation mode 811 When this is enabled (which it normally is), indentation commands 812 such as ‘C-j’ indent lines of code according to their syntactic 813 structure. Otherwise, a line is simply indented to the same level 814 as the previous one and ‘<TAB>’ adjusts the indentation in steps of 815 ‘c-basic-offset’. 816 817 Full details on how these minor modes work are at *note Electric 818Keys::, *note Auto-newlines::, *note Hungry WS Deletion::, *note Subword 819Movement::, and *note Indentation Engine Basics::. 820 821 You can toggle each of these minor modes on and off, and you can 822configure CC Mode so that it starts up with your favorite combination of 823them (*note Sample Init File::). By default, when you initialize a 824buffer, the comment style is set to the default for the major mode, 825electric mode and syntactic-indentation mode are enabled, but the other 826three modes are disabled. 827 828 CC Mode displays the current state of the first five of these minor 829modes on the mode line by appending characters to the major mode’s name: 830‘/’ or ‘*’ to indicate the comment style (respectively line or block), 831and one letter for each of the other minor modes which is enabled - ‘l’ 832for electric mode, ‘a’ for auto-newline mode, ‘h’ for hungry delete 833mode, and ‘w’ for subword mode. If the comment style was block and all 834the other modes were enabled, you’d see ‘C/*lahw’(2). 835 836 Here are the commands to toggle these modes: 837 838‘C-c C-k’ (‘c-toggle-comment-style’) 839 Toggle the comment style between line style and block style. In 840 modes (such as AWK Mode) which only have one of these styles, this 841 function does nothing. 842 843‘C-c C-l’ (‘c-toggle-electric-state’) 844 Toggle electric minor mode. When the command turns the mode off, 845 it also suppresses auto-newline mode. 846 847‘C-c C-a’ (‘c-toggle-auto-newline’) 848 Toggle auto-newline minor mode. When the command turns the mode 849 on, it also enables electric minor mode. 850 851‘M-x c-toggle-hungry-state’(3) 852 Toggle hungry-delete minor mode. 853 854‘M-x c-toggle-auto-hungry-state’(4) 855 Toggle both auto-newline and hungry delete minor modes. 856 857‘C-c C-w’ (‘M-x subword-mode’) 858 Toggle subword mode. 859 860‘M-x c-toggle-syntactic-indentation’ 861 Toggle syntactic-indentation mode. 862 863 Common to all the toggle functions above is that if they are called 864programmatically, they take an optional numerical argument. For 865‘c-toggle-comment style’, a positive value will select block comments, a 866negative value will select line comments. For the other functions, a 867positive value will turn on the minor mode (or both of them in the case 868of ‘c-toggle-auto-hungry-state’) and a negative value will turn it (or 869them) off. 870 871 ---------- Footnotes ---------- 872 873 (1) You can emphasize non-default style comments in your code by 874giving their delimiters ‘font-lock-warning-face’. *Note Wrong Comment 875Style::. 876 877 (2) The ‘C’ would be replaced with the name of the language in 878question for the other languages CC Mode supports. 879 880 (3) Prior to CC Mode 5.31, this command was bound to ‘C-c C-d’. 881 882 (4) Prior to CC Mode 5.31, this command was bound to ‘C-c C-t’. 883 884 885File: ccmode.info, Node: Electric Keys, Next: Auto-newlines, Prev: Minor Modes, Up: Commands 886 8874.6 Electric Keys and Keywords 888============================== 889 890Most punctuation keys provide “electric” behavior: as well as inserting 891themselves they perform some other action, such as reindenting the line. 892This reindentation saves you from having to reindent a line manually 893after typing, say, a ‘}’. A few keywords, such as ‘else’, also trigger 894electric action. 895 896 You can inhibit the electric behavior described here by disabling 897electric minor mode (*note Minor Modes::). 898 899 Common to all these keys is that they only behave electrically when 900used in normal code (as contrasted with getting typed in a string 901literal or comment). Those which cause re-indentation do so only when 902‘c-syntactic-indentation’ has a non-‘nil’ value (which it does by 903default). 904 905 These keys and keywords are: 906 907‘#’ 908 Pound (bound to ‘c-electric-pound’) is electric when typed as the 909 first non-whitespace character on a line and not within a macro 910 definition. In this case, the variable ‘c-electric-pound-behavior’ 911 is consulted for the electric behavior. This variable takes a list 912 value, although the only element currently defined is ‘alignleft’, 913 which tells this command to force the ‘#’ character into column 914 zero. This is useful for entering preprocessor macro definitions. 915 916 Pound is not electric in AWK buffers, where ‘#’ starts a comment, 917 and is bound to ‘self-insert-command’ like any typical printable 918 character. 919 920‘*’ 921‘/’ 922 A star (bound to ‘c-electric-star’) or a slash (‘c-electric-slash’) 923 causes reindentation when you type it as the second component of a 924 C style block comment opener (‘/*’) or a C++ line comment opener 925 (‘//’) respectively, but only if the comment opener is the first 926 thing on the line (i.e., there’s only whitespace before it). 927 928 Additionally, you can configure CC Mode so that typing a slash at 929 the start of a line within a block comment will terminate the 930 comment. You don’t need to have electric minor mode enabled to get 931 this behavior. *Note Clean-ups::. 932 933 In AWK mode, ‘*’ and ‘/’ do not delimit comments and are not 934 electric. 935 936‘<’ 937‘>’ 938 A less-than or greater-than sign (bound to ‘c-electric-lt-gt’) is 939 electric in two circumstances: when it is an angle bracket in a C++ 940 ‘template’ declaration (and similar constructs in other languages) 941 and when it is the second of two ‘<’ or ‘>’ characters in a C++ 942 style stream operator. In either case, the line is reindented. 943 Angle brackets in C ‘#include’ directives are not electric. 944 945‘(’ 946‘)’ 947 The normal parenthesis characters ‘(’ and ‘)’ (bound to 948 ‘c-electric-paren’) reindent the current line. This is useful for 949 getting the closing parenthesis of an argument list aligned 950 automatically. 951 952 You can also configure CC Mode to insert a space automatically 953 between a function name and the ‘(’ you’ve just typed, and to 954 remove it automatically after typing ‘)’, should the argument list 955 be empty. You don’t need to have electric minor mode enabled to 956 get these actions. *Note Clean-ups::. 957 958‘{’ 959‘}’ 960 Typing a brace (bound to ‘c-electric-brace’) reindents the current 961 line. Also, one or more newlines might be inserted if auto-newline 962 minor mode is enabled. *Note Auto-newlines::. Additionally, you 963 can configure CC Mode to compact excess whitespace inserted by 964 auto-newline mode in certain circumstances. *Note Clean-ups::. 965 966‘:’ 967 Typing a colon (bound to ‘c-electric-colon’) reindents the current 968 line. Additionally, one or more newlines might be inserted if 969 auto-newline minor mode is enabled. *Note Auto-newlines::. If you 970 type a second colon immediately after such an auto-newline, by 971 default the whitespace between the two colons is removed, leaving a 972 C++ scope operator. *Note Clean-ups::. 973 974 If you prefer, you can insert ‘::’ in a single operation, avoiding 975 all these spurious reindentations, newlines, and clean-ups. *Note 976 Other Commands::. 977 978‘;’ 979‘,’ 980 Typing a semicolon or comma (bound to ‘c-electric-semi&comma’) 981 reindents the current line. Also, a newline might be inserted if 982 auto-newline minor mode is enabled. *Note Auto-newlines::. 983 Additionally, you can configure CC Mode so that when auto-newline 984 has inserted whitespace after a ‘}’, it will be removed again when 985 you type a semicolon or comma just after it. *Note Clean-ups::. 986 987 -- Command: c-electric-continued-statement 988 989 Certain keywords are electric, causing reindentation when they are 990 preceded only by whitespace on the line. The keywords are those 991 that continue an earlier statement instead of starting a new one: 992 ‘else’, ‘while’, ‘catch’ (only in C++ and Java) and ‘finally’ (only 993 in Java). 994 995 An example: 996 997 for (i = 0; i < 17; i++) 998 if (a[i]) 999 res += a[i]->offset; 1000 else 1001 1002 Here, the ‘else’ should be indented like the preceding ‘if’, since 1003 it continues that statement. CC Mode will automatically reindent 1004 it after the ‘else’ has been typed in full, since only then is it 1005 possible to decide whether it’s a new statement or a continuation 1006 of the preceding ‘if’. 1007 1008 CC Mode uses Abbrev mode (*note (emacs)Abbrevs::) to accomplish 1009 this. It’s therefore turned on by default in all language modes 1010 except IDL mode, since CORBA IDL doesn’t have any statements. 1011 1012 1013File: ccmode.info, Node: Auto-newlines, Next: Hungry WS Deletion, Prev: Electric Keys, Up: Commands 1014 10154.7 Auto-newline Insertion 1016========================== 1017 1018When you have “Auto-newline minor mode” enabled (*note Minor Modes::), 1019CC Mode inserts newlines for you automatically (in certain syntactic 1020contexts) when you type a left or right brace, a colon, a semicolon, or 1021a comma. Sometimes a newline appears before the character you type, 1022sometimes after it, sometimes both. 1023 1024 Auto-newline only triggers when the following conditions hold: 1025 1026 • Auto-newline minor mode is enabled, as evidenced by the indicator 1027 ‘a’ after the mode name on the modeline (e.g., ‘C/a’ or ‘C/la’). 1028 1029 • The character was typed at the end of a line, or with only 1030 whitespace after it, and possibly a ‘\’ escaping the newline. 1031 1032 • The character is not on its own line already. (This applies only 1033 to insertion of a newline _before_ the character.) 1034 1035 • The character was not typed inside of a literal (1). 1036 1037 • No numeric argument was supplied to the command (i.e., it was typed 1038 as normal, with no ‘C-u’ prefix). 1039 1040 You can configure the precise circumstances in which newlines get 1041inserted (*note Custom Auto-newlines::). Typically, the style system 1042(*note Styles::) will have set this up for you, so you probably won’t 1043have to bother. 1044 1045 Sometimes CC Mode inserts an auto-newline where you don’t want one, 1046such as after a ‘}’ when you’re about to type a ‘;’. Hungry deletion 1047can help here (*note Hungry WS Deletion::), or you can activate an 1048appropriate “clean-up”, which will remove the excess whitespace after 1049you’ve typed the ‘;’. See *note Clean-ups:: for a full description. 1050See also *note Electric Keys:: for a summary of clean-ups listed by key. 1051 1052 ---------- Footnotes ---------- 1053 1054 (1) A “literal” is defined as any comment, string, or preprocessor 1055macro definition. These constructs are also known as “syntactic 1056whitespace” since they are usually ignored when scanning C code. 1057 1058 1059File: ccmode.info, Node: Hungry WS Deletion, Next: Subword Movement, Prev: Auto-newlines, Up: Commands 1060 10614.8 Hungry Deletion of Whitespace 1062================================= 1063 1064If you want to delete an entire block of whitespace at point, you can 1065use “hungry deletion”. This deletes all the contiguous whitespace 1066either before point or after point in a single operation. “Whitespace” 1067here includes tabs and newlines, but not comments or preprocessor 1068commands. Hungry deletion can markedly cut down on the number of times 1069you have to hit deletion keys when, for example, you’ve made a mistake 1070on the preceding line and have already pressed ‘C-j’. 1071 1072 Hungry deletion is a simple feature that some people find extremely 1073useful. In fact, you might find yourself wanting it in *all* your 1074editing modes! 1075 1076 Loosely speaking, in what follows, “<DEL>” means “the backspace key” 1077and “<DELETE>” means “the forward delete key”. This is discussed in 1078more detail below. 1079 1080 There are two different ways you can use hungry deletion: 1081 1082Using “Hungry Delete Mode” with ‘<DEL>’ and ‘C-d’ 1083 Here you toggle Hungry Delete minor mode with ‘M-x 1084 c-toggle-hungry-state’(1) (*note Minor Modes::.) This makes 1085 ‘<DEL>’ and ‘C-d’ do backwards and forward hungry deletion. 1086 1087 ‘<DEL>’ (‘c-electric-backspace’) 1088 This command is run by default when you hit the ‘<DEL>’ key. 1089 When hungry delete mode is enabled, it deletes any amount of 1090 whitespace in the backwards direction. Otherwise, or when 1091 used with a prefix argument or in a literal (*note 1092 Auto-newlines::), the command just deletes backwards in the 1093 usual way. (More precisely, it calls the function contained 1094 in the variable ‘c-backspace-function’, passing it the prefix 1095 argument, if any.) 1096 1097 ‘c-backspace-function’ 1098 Hook that gets called by ‘c-electric-backspace’ when it 1099 doesn’t do an “electric” deletion of the preceding whitespace. 1100 The default value is ‘backward-delete-char-untabify’ (*note 1101 (elisp)Deletion::, the function which deletes a single 1102 character. 1103 1104 ‘C-d’ (‘c-electric-delete-forward’) 1105 This function, which is bound to ‘C-d’ by default, works just 1106 like ‘c-electric-backspace’ but in the forward direction. 1107 When it doesn’t do an “electric” deletion of the following 1108 whitespace, it just does ‘delete-char’, more or less. 1109 (Strictly speaking, it calls the function in 1110 ‘c-delete-function’ with the prefix argument.) 1111 1112 ‘c-delete-function’ 1113 Hook that gets called by ‘c-electric-delete-forward’ when it 1114 doesn’t do an “electric” deletion of the following whitespace. 1115 The default value is ‘delete-char’. 1116 1117Using Distinct Bindings 1118 The other (newer and recommended) way to use hungry deletion is to 1119 perform ‘c-hungry-delete-backwards’ and ‘c-hungry-delete-forward’ 1120 directly through their key sequences rather than using the minor 1121 mode toggling. 1122 1123 ‘C-c C-<DEL>’, or ‘C-c <DEL>’ (‘c-hungry-delete-backwards’)(2) 1124 Delete any amount of whitespace in the backwards direction 1125 (regardless whether hungry-delete mode is enabled or not). 1126 This command is bound to both ‘C-c C-<DEL>’ and ‘C-c <DEL>’, 1127 since the more natural one, ‘C-c C-<DEL>’, is sometimes 1128 difficult to type at a character terminal. 1129 1130 ‘C-c C-d’, ‘C-c C-<DELETE>’, or ‘C-c <DELETE>’ (‘c-hungry-delete-forward’) 1131 Delete any amount of whitespace in the forward direction 1132 (regardless whether hungry-delete mode is enabled or not). 1133 This command is bound to both ‘C-c C-<Delete>’ and ‘C-c 1134 <Delete>’ for the same reason as for <DEL> above. 1135 1136 When we talk about ‘<DEL>’, and ‘<Delete>’ above, we actually do so 1137without connecting them to the physical keys commonly known as 1138<Backspace> and <Delete>. The default bindings to those two keys 1139depends on the flavor of (X)Emacs you are using. 1140 1141 In XEmacs 20.3 and beyond, the <Backspace> key is bound to 1142‘c-electric-backspace’ and the <Delete> key is bound to 1143‘c-electric-delete’. You control the direction it deletes in by setting 1144the variable ‘delete-key-deletes-forward’, a standard XEmacs variable. 1145When this variable is non-‘nil’, ‘c-electric-delete’ will do forward 1146deletion with ‘c-electric-delete-forward’, otherwise it does backward 1147deletion with ‘c-electric-backspace’. Similarly, ‘C-c <Delete>’ and 1148‘C-c C-<Delete>’ are bound to ‘c-hungry-delete’ which is controlled in 1149the same way by ‘delete-key-deletes-forward’. 1150 1151 Emacs 21 and later automatically binds <Backspace> and <Delete> to 1152‘DEL’ and ‘C-d’ according to your environment, and CC Mode extends those 1153bindings to ‘C-c C-<Backspace>’ etc. If you need to change the bindings 1154through ‘normal-erase-is-backspace-mode’ then CC Mode will also adapt 1155its extended bindings accordingly. 1156 1157 In earlier (X)Emacs versions, CC Mode doesn’t bind either <Backspace> 1158or <Delete> directly. Only the key codes ‘DEL’ and ‘C-d’ are bound, and 1159it’s up to the default bindings to map the physical keys to them. You 1160might need to modify this yourself if the defaults are unsuitable. 1161 1162 Getting your <Backspace> and <Delete> keys properly set up can 1163sometimes be tricky. The information in *note (emacs)DEL Does Not 1164Delete::, might be helpful if you’re having trouble with this in GNU 1165Emacs. 1166 1167 ---------- Footnotes ---------- 1168 1169 (1) Prior to CC Mode 5.31, this command was bound to ‘C-c C-d’. ‘C-c 1170C-d’ is now the default binding for ‘c-hungry-delete-forward’. 1171 1172 (2) This command was formerly known as ‘c-hungry-backspace’. 1173 1174 1175File: ccmode.info, Node: Subword Movement, Next: Other Commands, Prev: Hungry WS Deletion, Up: Commands 1176 11774.9 Subword Movement and Editing 1178================================ 1179 1180In spite of the GNU Coding Standards, it is popular to name a symbol by 1181mixing uppercase and lowercase letters, e.g., ‘GtkWidget’, 1182‘EmacsFrameClass’, or ‘NSGraphicsContext’. Here we call these mixed 1183case symbols “nomenclatures”. Also, each capitalized (or completely 1184uppercase) part of a nomenclature is called a “subword”. Here are some 1185examples: 1186 1187Nomenclature Subwords 1188——————————————————— 1189‘GtkWindow’ ‘Gtk’ and ‘Window’ 1190‘EmacsFrameClass’ ‘Emacs’, ‘Frame’, and ‘Class’ 1191‘NSGraphicsContext’ ‘NS’, ‘Graphics’, and ‘Context’ 1192 1193 The subword minor mode replaces the basic word oriented movement and 1194editing commands with variants that recognize subwords in a nomenclature 1195and treat them as separate words: 1196 1197Key Word oriented command Subword oriented command 1198—————————————————————————- 1199‘M-f’ ‘forward-word’ ‘c-forward-subword’ 1200‘M-b’ ‘backward-word’ ‘c-backward-subword’ 1201‘M-@’ ‘mark-word’ ‘c-mark-subword’ 1202‘M-d’ ‘kill-word’ ‘c-kill-subword’ 1203‘M-<DEL>’ ‘backward-kill-word’ ‘c-backward-kill-subword’ 1204‘M-t’ ‘transpose-words’ ‘c-transpose-subwords’ 1205‘M-c’ ‘capitalize-word’ ‘c-capitalize-subword’ 1206‘M-u’ ‘upcase-word’ ‘c-upcase-subword’ 1207‘M-l’ ‘downcase-word’ ‘c-downcase-subword’ 1208 1209 Note that if you have changed the key bindings for the word oriented 1210commands in your ‘.emacs’ or a similar place, the keys you have 1211configured are also used for the corresponding subword oriented 1212commands. 1213 1214 Type ‘C-c C-w’ to toggle subword mode on and off. To make the mode 1215turn on automatically, put the following code in your ‘.emacs’: 1216 1217 (add-hook 'c-mode-common-hook 1218 (lambda () (subword-mode 1))) 1219 1220 As a bonus, you can also use ‘subword-mode’ in non-CC Mode buffers by 1221typing ‘M-x subword-mode’. 1222 1223 1224File: ccmode.info, Node: Other Commands, Prev: Subword Movement, Up: Commands 1225 12264.10 Other Commands 1227=================== 1228 1229Here are the various other commands that didn’t fit anywhere else: 1230 1231‘C-c .’ (‘c-set-style’) 1232 Switch to the specified style in the current buffer. Use like 1233 this: 1234 1235 C-c . STYLE-NAME <RET> 1236 1237 You can use the <TAB> in the normal way to do completion on the 1238 style name. Note that all style names are case insensitive, even 1239 the ones you define yourself. 1240 1241 Setting a style in this way does _not_ automatically reindent your 1242 file. For commands that you can use to view the effect of your 1243 changes, see *note Indentation Commands:: and *note Filling and 1244 Breaking::. 1245 1246 For details of the CC Mode style system, see *note Styles::. 1247 1248‘C-c :’ (‘c-scope-operator’) 1249 In C++, it is also sometimes desirable to insert the double-colon 1250 scope operator without performing the electric behavior of colon 1251 insertion. ‘C-c :’ does just this. 1252 1253‘C-c C-z’ (‘c-display-defun-name’) 1254 Display the current function name, if any, in the minibuffer. 1255 Additionally, if a prefix argument is given, push the function name 1256 to the kill ring. If there is no current function, 1257 ‘c-display-defun-name’ does nothing. In Emacs, you can use this 1258 command in the middle of an interactive search if you set the 1259 customizable option ‘isearch-allow-scroll’ to non-‘nil’. *Note 1260 (emacs)Not Exiting Isearch::. 1261 1262‘C-c C-\’ (‘c-backslash-region’) 1263 This function inserts and aligns or deletes end-of-line backslashes 1264 in the current region. These are typically used in multi-line 1265 macros. 1266 1267 With no prefix argument, it inserts any missing backslashes and 1268 aligns them according to the ‘c-backslash-column’ and 1269 ‘c-backslash-max-column’ variables. With a prefix argument, it 1270 deletes any backslashes. 1271 1272 The function does not modify blank lines at the start of the 1273 region. If the region ends at the start of a line, it always 1274 deletes the backslash (if any) at the end of the previous line. 1275 1276 To customize the precise workings of this command, *note Custom 1277 Macros::. 1278 1279The recommended line breaking function, ‘c-context-line-break’ (*note 1280Filling and Breaking::), is especially nice if you edit multiline macros 1281frequently. When used inside a macro, it automatically inserts and 1282adjusts the mandatory backslash at the end of the line to keep the macro 1283together, and it leaves the point at the right indentation column for 1284the code. Thus you can write code inside macros almost exactly as you 1285can elsewhere, without having to bother with the trailing backslashes. 1286 1287‘C-c C-e’ (‘c-macro-expand’) 1288 This command expands C, C++, Objective C or Pike macros in the 1289 region, using an appropriate external preprocessor program. 1290 Normally it displays its output in a temporary buffer, but if you 1291 give it a prefix arg (with ‘C-u C-c C-e’) it will overwrite the 1292 original region with the expansion. 1293 1294 The command does not work in any of the other modes, and the key 1295 sequence is not bound in these other modes. 1296 1297 ‘c-macro-expand’ isn’t actually part of CC Mode, even though it is 1298 bound to a CC Mode key sequence. If you need help setting it up or 1299 have other problems with it, you can either read its source code or 1300 ask for help in the standard (X)Emacs forums. 1301 1302 1303File: ccmode.info, Node: Font Locking, Next: Config Basics, Prev: Commands, Up: Top 1304 13055 Font Locking 1306************** 1307 1308CC Mode provides font locking for its supported languages by supplying 1309patterns for use with Font Lock mode. This means that you get distinct 1310faces on the various syntactic parts such as comments, strings, keywords 1311and types, which is very helpful in telling them apart at a glance and 1312discovering syntactic errors. *Note (emacs)Font Lock::, for ways to 1313enable font locking in CC Mode buffers. 1314 1315 *Please note:* The font locking in AWK mode is currently not 1316integrated with the rest of CC Mode. Only the last section of this 1317chapter, *note AWK Mode Font Locking::, applies to AWK. The other 1318sections apply to the other languages. 1319 1320* Menu: 1321 1322* Font Locking Preliminaries:: 1323* Faces:: 1324* Doc Comments:: 1325* Wrong Comment Style:: 1326* Misc Font Locking:: 1327* AWK Mode Font Locking:: 1328 1329 1330File: ccmode.info, Node: Font Locking Preliminaries, Next: Faces, Prev: Font Locking, Up: Font Locking 1331 13325.1 Font Locking Preliminaries 1333============================== 1334 1335The font locking for most of the CC Mode languages were provided 1336directly by the Font Lock package prior to version 5.30 of CC Mode. In 1337the transition to CC Mode the patterns have been reworked completely and 1338are applied uniformly across all the languages except AWK mode, just 1339like the indentation rules (although each language still has some 1340peculiarities of its own, of course). Since the languages previously 1341had completely separate font locking patterns, this means that it’s a 1342bit different in most languages now. 1343 1344 The main goal for the font locking in CC Mode is accuracy, to provide 1345a dependable aid in recognizing the various constructs. Some, like 1346strings and comments, are easy to recognize while others, like 1347declarations and types, can be very tricky. CC Mode can go to great 1348lengths to recognize declarations and casts correctly, especially when 1349the types aren’t recognized by standard patterns. This is a fairly 1350demanding analysis which can be slow on older hardware, and it can 1351therefore be disabled by choosing a lower decoration level with the 1352variable ‘font-lock-maximum-decoration’ (*note (emacs)Font Lock::). 1353 1354 The decoration levels are used as follows: 1355 1356 1. Minimal font locking: Fontify only comments, strings and 1357 preprocessor directives (in the languages that use cpp). 1358 1359 2. Fast font locking: In addition to level 1, fontify keywords, simple 1360 types and declarations that are easy to recognize. The variables 1361 ‘*-font-lock-extra-types’ (where ‘*’ is the name of the language) 1362 are used to recognize types (see below). Documentation comments 1363 like Javadoc are fontified according to ‘c-doc-comment-style’ 1364 (*note Doc Comments::). 1365 1366 Use this if you think the font locking is too slow. It’s the 1367 closest corresponding level to level 3 in the old font lock 1368 patterns. 1369 1370 3. Accurate font locking: Like level 2 but uses a different approach 1371 that can recognize types and declarations much more accurately. 1372 The ‘*-font-lock-extra-types’ variables are still used, but user 1373 defined types are recognized correctly anyway in most cases. 1374 Therefore those variables should be fairly restrictive and not 1375 contain patterns that are uncertain. 1376 1377 This level is designed for fairly modern hardware and a font lock 1378 support mode like Lazy Lock or Just-in-time Lock mode that only 1379 fontifies the parts that are actually shown. Fontifying the whole 1380 buffer at once can easily get bothersomely slow even on 1381 contemporary hardware. *Note (emacs)Font Lock::. 1382 1383 Since user defined types are hard to recognize you can provide 1384additional regexps to match those you use: 1385 1386 -- User Option: c-font-lock-extra-types 1387 -- User Option: c++-font-lock-extra-types 1388 -- User Option: objc-font-lock-extra-types 1389 -- User Option: java-font-lock-extra-types 1390 -- User Option: idl-font-lock-extra-types 1391 -- User Option: pike-font-lock-extra-types 1392 For each language there’s a variable ‘*-font-lock-extra-types’, 1393 where ‘*’ stands for the language in question. It contains a list 1394 of regexps that matches identifiers that should be recognized as 1395 types, e.g., ‘\\sw+_t’ to recognize all identifiers ending with 1396 ‘_t’ as is customary in C code. Each regexp should not match more 1397 than a single identifier. 1398 1399 The default values contain regexps for many types in standard 1400 runtime libraries that are otherwise difficult to recognize, and 1401 patterns for standard type naming conventions like the ‘_t’ suffix 1402 in C and C++. Java, Objective-C and Pike have as a convention to 1403 start class names with capitals, so there are patterns for that in 1404 those languages. 1405 1406 Despite the names of these variables, they are not only used for 1407 fontification but in other places as well where CC Mode needs to 1408 recognize types. 1409 1410 1411File: ccmode.info, Node: Faces, Next: Doc Comments, Prev: Font Locking Preliminaries, Up: Font Locking 1412 14135.2 Faces 1414========= 1415 1416CC Mode attempts to use the standard faces for programming languages in 1417accordance with their intended purposes as far as possible. No extra 1418faces are currently provided, with the exception of a replacement face 1419‘c-invalid-face’ for emacsen that don’t provide 1420‘font-lock-warning-face’. 1421 1422 • Normal comments are fontified in ‘font-lock-comment-face’. 1423 1424 • Comments that are recognized as documentation (*note Doc 1425 Comments::) get ‘font-lock-doc-face’ (Emacs) or 1426 ‘font-lock-doc-string-face’ (XEmacs) if those faces exist. If they 1427 don’t then ‘font-lock-comment-face’ is used. 1428 1429 • String and character literals are fontified in 1430 ‘font-lock-string-face’. 1431 1432 • Keywords are fontified with ‘font-lock-keyword-face’. 1433 1434 • ‘font-lock-function-name-face’ is used for function names in 1435 declarations and definitions, and classes in those contexts. It’s 1436 also used for preprocessor defines with arguments. 1437 1438 • Variables in declarations and definitions, and other identifiers in 1439 such variable contexts, get ‘font-lock-variable-name-face’. It’s 1440 also used for preprocessor defines without arguments. 1441 1442 • Builtin constants are fontified in ‘font-lock-constant-face’ if it 1443 exists, ‘font-lock-reference-face’ otherwise. As opposed to the 1444 preceding two faces, this is used on the names in expressions, and 1445 it’s not used in declarations, even if there happen to be a ‘const’ 1446 in them somewhere. 1447 1448 • ‘font-lock-type-face’ is put on types (both predefined and user 1449 defined) and classes in type contexts. 1450 1451 • Label identifiers get ‘font-lock-constant-face’ if it exists, 1452 ‘font-lock-reference-face’ otherwise. 1453 1454 • Name qualifiers and identifiers for scope constructs are fontified 1455 like labels. 1456 1457 • Special markup inside documentation comments are also fontified 1458 like labels. 1459 1460 • Preprocessor directives get ‘font-lock-preprocessor-face’ if it 1461 exists (i.e., XEmacs). In Emacs they get ‘font-lock-builtin-face’ 1462 or ‘font-lock-reference-face’, for lack of a closer equivalent. 1463 1464 • Some kinds of syntactic errors are fontified with 1465 ‘font-lock-warning-face’ in Emacs. In older XEmacs versions 1466 there’s no corresponding standard face, so there a special 1467 ‘c-invalid-face’ is used, which is defined to stand out sharply by 1468 default. 1469 1470 Note that it’s not used for ‘#error’ or ‘#warning’ directives, 1471 since those aren’t syntactic errors in themselves. 1472 1473 1474File: ccmode.info, Node: Doc Comments, Next: Wrong Comment Style, Prev: Faces, Up: Font Locking 1475 14765.3 Documentation Comments 1477========================== 1478 1479There are various tools to supply documentation in the source as 1480specially structured comments, e.g., the standard Javadoc tool in Java. 1481CC Mode provides an extensible mechanism to fontify such comments and 1482the special markup inside them. 1483 1484 -- User Option: c-doc-comment-style 1485 This is a style variable that specifies which documentation comment 1486 style to recognize, e.g., ‘javadoc’ for Javadoc comments. 1487 1488 The value may also be a list of styles, in which case all of them 1489 are recognized simultaneously (presumably with markup cues that 1490 don’t conflict). 1491 1492 The value may also be an association list to specify different 1493 comment styles for different languages. The symbol for the major 1494 mode is then looked up in the alist, and the value of that element 1495 is interpreted as above if found. If it isn’t found then the 1496 symbol ‘other’ is looked up and its value is used instead. 1497 1498 The default value for ‘c-doc-comment-style’ is 1499 ‘((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))’. 1500 1501 Note that CC Mode uses this variable to set other variables that 1502 handle fontification etc. That’s done at mode initialization or 1503 when you switch to a style which sets this variable. Thus, if you 1504 change it in some other way, e.g., interactively in a CC Mode 1505 buffer, you will need to do ‘M-x java-mode’ (or whatever mode 1506 you’re currently using) to reinitialize. 1507 1508 Note also that when CC Mode starts up, the other variables are 1509 modified before the mode hooks are run. If you change this 1510 variable in a mode hook, you’ll have to call 1511 ‘c-setup-doc-comment-style’ afterwards to redo that work. 1512 1513 CC Mode currently provides handing of the following doc comment 1514styles: 1515 1516‘javadoc’ 1517 Javadoc comments, the standard tool in Java. 1518 1519‘autodoc’ 1520 For Pike autodoc markup, the standard in Pike. 1521 1522‘gtkdoc’ 1523 For GtkDoc markup, widely used in the Gnome community. 1524 1525 The above is by no means complete. If you’d like to see support for 1526other doc comment styles, please let us know (*note Mailing Lists and 1527Bug Reports::). 1528 1529 You can also write your own doc comment fontification support to use 1530with ‘c-doc-comment-style’: Supply a variable or function 1531‘*-font-lock-keywords’ where ‘*’ is the name you want to use in 1532‘c-doc-comment-style’. If it’s a variable, it’s prepended to 1533‘font-lock-keywords’. If it’s a function, it’s called at mode 1534initialization and the result is prepended. For an example, see 1535‘javadoc-font-lock-keywords’ in ‘cc-fonts.el’. It is even possible, to 1536a limited extent, to fontify constructs inside a doc comment with other 1537faces. For an example, see pike autodoc comment style towards the end 1538of ‘cc-fonts-el’. 1539 1540 If you add support for another doc comment style, please consider 1541contributing it: send a note to <bug-cc-mode@gnu.org>. 1542 1543 1544File: ccmode.info, Node: Wrong Comment Style, Next: Misc Font Locking, Prev: Doc Comments, Up: Font Locking 1545 15465.4 Marking “Wrong” style comments 1547================================== 1548 1549Most languages supported by CC Mode have two styles of comments, namely 1550block comments and line comments. Your project may have such a strong 1551preference for one of them, that you wish “wrong” style comments to be 1552clearly marked. 1553 1554 You can get CC Mode to do this by setting the default comment style, 1555if necessary, (*note Minor Modes::) and setting the customizable option 1556‘c-mark-wrong-style-of-comment’ to non-‘nil’. 1557 1558 -- Variable: c-mark-wrong-style-of-comment 1559 When this customizable option is non-‘nil’, comment delimiters 1560 which aren’t of the default style will be fontified with 1561 ‘font-lock-warning-face’. 1562 1563 1564File: ccmode.info, Node: Misc Font Locking, Next: AWK Mode Font Locking, Prev: Wrong Comment Style, Up: Font Locking 1565 15665.5 Miscellaneous Font Locking 1567============================== 1568 1569In some languages, particularly in C++, there are constructs which are 1570syntactically ambiguous—they could be either declarations or 1571expressions, and CC Mode cannot tell for sure which. Often such a 1572construct is one of the operators ‘*’ or ‘&’ surrounded by two 1573identifiers. 1574 1575 Experience shows that very often when such a construct is a 1576declaration it will be written with the operator touching exactly one of 1577the identifiers, like: 1578 1579 foo *bar 1580 or 1581 foo& bar 1582 1583 . Whether such code is fontified depends on the setting of 1584‘c-asymmetry-fontification-flag’. 1585 1586 -- Variable: c-asymmetry-fontification-flag 1587 When ‘c-asymmetry-fontification-flag’ is non-nil (which it is by 1588 default), code like the above, with white space either before or 1589 after the operator, but not both, is fontified as a declaration. 1590 When the variable is nil, such a construct gets the default face. 1591 1592 When the construct is an expression there will often be white space 1593both before and after the operator or there will be no white space 1594around it at all, like: 1595 1596 foo * bar 1597 or 1598 foo&bar 1599 . 1600 1601 Such code is not fontified as a declaration. (Typically, the 1602identifiers don’t get a non-default face.) 1603 1604 For clarity’s sake, we emphasize that the “asymmetry” rule in this 1605section only applies when CC Mode cannot disambiguate a construct in any 1606other way. 1607 1608 1609File: ccmode.info, Node: AWK Mode Font Locking, Prev: Misc Font Locking, Up: Font Locking 1610 16115.6 AWK Mode Font Locking 1612========================= 1613 1614The general appearance of font-locking in AWK mode is much like in any 1615other programming mode. *Note (elisp)Faces for Font Lock::. 1616 1617 The following faces are, however, used in a non-standard fashion in 1618AWK mode: 1619 1620‘font-lock-variable-name-face’ 1621 This face was intended for variable declarations. Since variables 1622 are not declared in AWK, this face is used instead for AWK system 1623 variables (such as ‘NF’) and “Special File Names” (such as 1624 ‘"/dev/stderr"’). 1625 1626‘font-lock-builtin-face’ (Emacs)/‘font-lock-preprocessor-face’ (XEmacs) 1627 This face is normally used for preprocessor directives in CC Mode. 1628 There are no such things in AWK, so this face is used instead for 1629 standard functions (such as ‘match’). 1630 1631‘font-lock-string-face’ 1632 As well as being used for strings, including localizable strings, 1633 (delimited by ‘"’ and ‘_"’), this face is also used for AWK regular 1634 expressions (delimited by ‘/’). 1635 1636‘font-lock-warning-face’ (Emacs)/‘c-invalid-face’ (XEmacs) 1637 This face highlights the following syntactically invalid AWK 1638 constructs: 1639 1640 • An unterminated string or regular expression. Here the 1641 opening delimiter (‘"’ or ‘/’ or ‘_"’) is displayed in 1642 ‘font-lock-warning-face’. This is most noticeable when typing 1643 in a new string/regular expression into a buffer, when the 1644 warning-face serves as a continual reminder to terminate the 1645 construct. 1646 1647 AWK mode fontifies unterminated strings/regular expressions 1648 differently from other modes: Only the text up to the end of 1649 the line is fontified as a string (escaped newlines being 1650 handled correctly), rather than the text up to the next string 1651 quote. 1652 1653 • A space between the function name and opening parenthesis when 1654 calling a user function. The last character of the function 1655 name and the opening parenthesis are highlighted. This 1656 font-locking rule will spuriously highlight a valid 1657 concatenation expression where an identifier precedes a 1658 parenthesized expression. Unfortunately. 1659 1660 • Whitespace following the ‘\’ in what otherwise looks like an 1661 escaped newline. The ‘\’ is highlighted. 1662 1663 1664File: ccmode.info, Node: Config Basics, Next: Custom Filling and Breaking, Prev: Font Locking, Up: Top 1665 16666 Configuration Basics 1667********************** 1668 1669You configure CC Mode by setting Lisp variables and calling (and perhaps 1670writing) Lisp functions(1), which is usually done by adding code to an 1671Emacs initialization file. This file might be ‘site-start.el’ or 1672‘.emacs’ or ‘init.el’ or ‘default.el’ or perhaps some other file. *Note 1673(emacs)Init File::. For the sake of conciseness, we just call this file 1674“your ‘.emacs’” throughout the rest of the manual. 1675 1676 Several of these variables (currently 16), are known collectively as 1677“style variables”. CC Mode provides a special mechanism, known as 1678“styles” to make it easier to set these variables as a group, to 1679“inherit” settings from one style into another, and so on. Style 1680variables remain ordinary Lisp variables, whose values can be read and 1681changed independently of the style system. *Note Style Variables::. 1682 1683 There are several ways you can write the code, depending on the 1684precise effect you want—they are described further down on this page. 1685If you are new to CC Mode, we suggest you begin with the simplest 1686method, “Top-level commands or the customization interface”. 1687 1688 If you make conflicting settings in several of these ways, the way 1689that takes precedence is the one that appears latest in this list: 1690 Style 1691 File Style(2) 1692 Top-level command or “customization interface” 1693 Hook 1694 File Local Variable setting 1695 1696 Here is a summary of the different ways of writing your configuration 1697settings: 1698 1699Top-level commands or the “customization interface” 1700 Most simply, you can write ‘setq’ and similar commands at the top 1701 level of your ‘.emacs’ file. When you load a CC Mode buffer, it 1702 initializes its configuration from these global values (at least, 1703 for those settings you have given values to), so it makes sense to 1704 have these ‘setq’ commands run _before_ CC Mode is first 1705 initialized—in particular, before any call to ‘desktop-read’ (*note 1706 (emacs)Saving Emacs Sessions::). For example, you might set 1707 c-basic-offset thus: 1708 1709 (setq c-basic-offset 4) 1710 1711 You can use the more user friendly Customization interface instead, 1712 but this manual does not cover in detail how that works. To do 1713 this, start by typing ‘M-x customize-group <RET> c <RET>’. *Note 1714 (emacs)Easy Customization::. Emacs normally writes the 1715 customizations at the end of your ‘.emacs’ file. If you use 1716 ‘desktop-read’, you should edit your ‘.emacs’ to place the call to 1717 ‘desktop-read’ _after_ the customizations. 1718 1719 The first initialization of CC Mode puts a snapshot of the 1720 configuration settings into the special style ‘user’. *Note 1721 Built-in Styles::. 1722 1723 For basic use of Emacs, either of these ways of configuring is 1724 adequate. However, the settings are then the same in all CC Mode 1725 buffers and it can be clumsy to communicate them between 1726 programmers. For more flexibility, you’ll want to use one (or 1727 both) of CC Mode’s more sophisticated facilities, hooks and styles. 1728 1729Hooks 1730 An Emacs “hook” is a place to put Lisp functions that you want 1731 Emacs to execute later in specific circumstances. *Note 1732 (elisp)Hooks::. CC Mode supplies a main hook and a 1733 language-specific hook for each language it supports; any functions 1734 you put onto these hooks get executed as the last part of a 1735 buffer’s initialization. Typically you put most of your 1736 customization within the main hook, and use the language-specific 1737 hooks to vary the customization settings between language modes. 1738 For example, if you wanted different (non-standard) values of 1739 ‘c-basic-offset’ in C Mode and Java Mode buffers, you could do it 1740 like this: 1741 1742 (defun my-c-mode-hook () 1743 (setq c-basic-offset 3)) 1744 (add-hook 'c-mode-hook 'my-c-mode-hook) 1745 1746 (defun my-java-mode-hook () 1747 (setq c-basic-offset 6)) 1748 (add-hook 'java-mode-hook 'my-java-mode-hook) 1749 1750 See *note CC Hooks:: for more details on the use of CC Mode hooks. 1751 1752Styles 1753 A CC Mode “style” is a coherent collection of customizations with a 1754 name. At any time, exactly one style is active in each CC Mode 1755 buffer, either the one you have selected or a default. CC Mode is 1756 delivered with several existing styles. Additionally, you can 1757 create your own styles, possibly based on these existing styles. 1758 If you worked in a programming team called the “Free Group”, which 1759 had its own coding standards, you might well have this in your 1760 ‘.emacs’ file: 1761 1762 (setq c-default-style '((java-mode . "java") 1763 (awk-mode . "awk") 1764 (other . "free-group-style"))) 1765 1766 See *note Styles:: for fuller details on using CC Mode styles and 1767 how to create them. 1768 1769File Local Variable setting 1770 A “file local variable setting” is a setting which applies to an 1771 individual source file. You put this in a “local variables list”, 1772 a special block at the end of the source file (*note 1773 (emacs)Specifying File Variables::). 1774 1775File Styles 1776 A “file style” is a rarely used variant of the “style” mechanism 1777 described above, which applies to an individual source file. *Note 1778 File Styles::. You use this by setting certain special variables 1779 in a local variables list (*note (emacs)Specifying File 1780 Variables::). 1781 1782Hooks with Styles 1783 For ultimate flexibility, you can use hooks and styles together. 1784 For example, if your team were developing a product which required 1785 a Linux driver, you’d probably want to use the “linux” style for 1786 the driver, and your own team’s style for the rest of the code. 1787 You could achieve this with code like this in your ‘.emacs’: 1788 1789 (defun my-c-mode-hook () 1790 (c-set-style 1791 (if (and (buffer-file-name) 1792 (string-match "/usr/src/linux" (buffer-file-name))) 1793 "linux" 1794 "free-group-style"))) 1795 (add-hook 'c-mode-hook 'my-c-mode-hook) 1796 1797 In a programming team, a hook is also a good place for each member 1798 to put his own personal preferences. For example, you might be the 1799 only person in your team who likes Auto-newline minor mode. You 1800 could have it enabled by default by placing the following in your 1801 ‘.emacs’: 1802 1803 (defun my-turn-on-auto-newline () 1804 (c-toggle-auto-newline 1)) 1805 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) 1806 1807* Menu: 1808 1809* CC Hooks:: 1810* Style Variables:: 1811* Styles:: 1812 1813 ---------- Footnotes ---------- 1814 1815 (1) DON’T PANIC!!! This isn’t difficult. 1816 1817 (2) In earlier versions of CC Mode, a File Style setting took 1818precedence over any other setting apart from a File Local Variable 1819setting. 1820 1821 1822File: ccmode.info, Node: CC Hooks, Next: Style Variables, Prev: Config Basics, Up: Config Basics 1823 18246.1 Hooks 1825========= 1826 1827CC Mode provides several hooks that you can use to customize the mode 1828for your coding style. The main hook is ‘c-mode-common-hook’; 1829typically, you’ll put the bulk of your customizations here. In 1830addition, each language mode has its own hook, allowing you to fine tune 1831your settings individually for the different CC Mode languages, and 1832there is a package initialization hook. Finally, there is 1833‘c-special-indent-hook’, which enables you to solve anomalous 1834indentation problems. It is described in *note Other Indentation::, not 1835here. All these hooks adhere to the standard Emacs conventions. 1836 1837 When you open a buffer, CC Mode first initializes it with the 1838currently active style (*note Styles::). Then it calls 1839‘c-mode-common-hook’, and finally it calls the language-specific hook. 1840Thus, any style settings done in these hooks will override those set by 1841‘c-default-style’. 1842 1843 -- Variable: c-initialization-hook 1844 Hook run only once per Emacs session, when CC Mode is initialized. 1845 This is a good place to change key bindings (or add new ones) in 1846 any of the CC Mode key maps. *Note Sample Init File::. 1847 1848 -- Variable: c-mode-common-hook 1849 Common hook across all languages. It’s run immediately before the 1850 language specific hook. 1851 1852 -- Variable: c-mode-hook 1853 -- Variable: c++-mode-hook 1854 -- Variable: objc-mode-hook 1855 -- Variable: java-mode-hook 1856 -- Variable: idl-mode-hook 1857 -- Variable: pike-mode-hook 1858 -- Variable: awk-mode-hook 1859 The language specific mode hooks. The appropriate one is run as 1860 the last thing when you enter that language mode. 1861 1862 Although these hooks are variables defined in CC Mode, you can give 1863them values before CC Mode’s code is loaded—indeed, this is the only way 1864to use ‘c-initialization-hook’. Their values aren’t overwritten when CC 1865Mode gets loaded. 1866 1867 Here’s a simplified example of what you can add to your ‘.emacs’ file 1868to do things whenever any CC Mode language is edited. See the Emacs 1869manuals for more information on customizing Emacs via hooks. *Note 1870Sample Init File::, for a more complete sample ‘.emacs’ file. 1871 1872 (defun my-c-mode-common-hook () 1873 ;; my customizations for all of c-mode and related modes 1874 (no-case-fold-search) 1875 ) 1876 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) 1877 1878 1879File: ccmode.info, Node: Style Variables, Next: Styles, Prev: CC Hooks, Up: Config Basics 1880 18816.2 Style Variables 1882=================== 1883 1884The variables that CC Mode’s style system control are called “style 1885variables”. Note that style variables are ordinary Lisp variables, 1886which the style system initializes; you can change their values at any 1887time (e.g., in a hook function). The style system can also set other 1888variables, to some extent. *Note Styles::. 1889 1890 “Style variables” are handled specially in several ways: 1891 1892 • Style variables are by default buffer-local variables. However, 1893 they can instead be made global by setting 1894 ‘c-style-variables-are-local-p’ to ‘nil’ before CC Mode is 1895 initialized. 1896 1897 • The default global binding of any style variable (with two 1898 exceptions - see below) is the special symbol ‘set-from-style’. 1899 When the style system initializes a buffer-local copy of a style 1900 variable for a CC Mode buffer, if its global binding is still that 1901 symbol then it will be set from the current style. Otherwise it 1902 will retain its global default(1). This “otherwise” happens, for 1903 example, when you’ve set the variable with ‘setq’ at the top level 1904 of your ‘.emacs’ (*note Config Basics::). 1905 1906 • The style variable ‘c-offsets-alist’ (*note c-offsets-alist::) is 1907 an association list with an element for each syntactic symbol. 1908 It’s handled a little differently from the other style variables. 1909 Its default global binding is the empty list ‘nil’, rather than 1910 ‘set-from-style’. Before the style system is initialized, you can 1911 add individual elements to ‘c-offsets-alist’ by calling 1912 ‘c-set-offset’ (*note c-offsets-alist::) just like you would set 1913 other style variables with ‘setq’. Those elements will then 1914 prevail when the style system later initializes a buffer-local copy 1915 of ‘c-offsets-alist’. 1916 1917 • The style variable ‘c-special-indent-hook’ is also handled in a 1918 special way. Styles can only add functions to this hook, not 1919 remove them, so any global settings you put on it are always 1920 preserved(2). The value you give this variable in a style 1921 definition can be either a function or a list of functions. 1922 1923 • The global bindings of the style variables get captured in the 1924 special ‘user’ style when the style system is first initialized. 1925 *Note Built-in Styles::, for details. 1926 1927 The style variables are: 1928‘c-indent-comment-alist’, ‘c-indent-comments-syntactically-p’ (*note 1929Indentation Commands::); 1930‘c-doc-comment-style’ (*note Doc Comments::); 1931‘c-block-comment-prefix’, ‘c-comment-prefix-regexp’ (*note Custom 1932Filling and Breaking::); 1933‘c-hanging-braces-alist’ (*note Hanging Braces::); 1934‘c-hanging-colons-alist’ (*note Hanging Colons::); 1935‘c-hanging-semi&comma-criteria’ (*note Hanging Semicolons and Commas::); 1936‘c-cleanup-list’ (*note Clean-ups::); 1937‘c-basic-offset’ (*note Customizing Indentation::); 1938‘c-offsets-alist’ (*note c-offsets-alist::); 1939‘c-comment-only-line-offset’ (*note Comment Line-Up::); 1940‘c-special-indent-hook’, ‘c-label-minimum-indentation’ (*note Other 1941Indentation::); 1942‘c-backslash-column’, ‘c-backslash-max-column’ (*note Custom Macros::). 1943 1944 ---------- Footnotes ---------- 1945 1946 (1) This is a big change from versions of CC Mode earlier than 5.26, 1947where such settings would get overridden by the style system unless 1948special precautions were taken. That was changed since it was 1949counterintuitive and confusing, especially to novice users. If your 1950configuration depends on the old overriding behavior, you can set the 1951variable ‘c-old-style-variable-behavior’ to non-‘nil’. 1952 1953 (2) This did not change in version 5.26. 1954 1955 1956File: ccmode.info, Node: Styles, Prev: Style Variables, Up: Config Basics 1957 19586.3 Styles 1959========== 1960 1961By “style” we mean the layout of the code—things like how many columns 1962to indent a block of code, whether an opening brace gets indented to the 1963level of the code it encloses, or of the construct that introduces it, 1964or “hangs” at the end of a line. 1965 1966 Most people only need to edit code formatted in just a few 1967well-defined and consistent styles. For example, their organization 1968might impose a “blessed” style that all its programmers must conform to. 1969Similarly, people who work on GNU software will have to use the GNU 1970coding style. Some shops are more lenient, allowing a variety of coding 1971styles, and as programmers come and go, there could be a number of 1972styles in use. For this reason, CC Mode makes it convenient for you to 1973set up logical groupings of customizations called “styles”, associate a 1974single name for any particular style, and pretty easily start editing 1975new or existing code using these styles. 1976 1977 As an alternative to writing a style definition yourself, you can 1978have CC Mode “guess” (at least part of) your style by looking at an 1979already formatted piece of your code, *note Guessing the Style::. 1980 1981* Menu: 1982 1983* Built-in Styles:: 1984* Choosing a Style:: 1985* Adding Styles:: 1986* Guessing the Style:: 1987* File Styles:: 1988 1989 1990File: ccmode.info, Node: Built-in Styles, Next: Choosing a Style, Prev: Styles, Up: Styles 1991 19926.3.1 Built-in Styles 1993--------------------- 1994 1995If you’re lucky, one of CC Mode’s built-in styles might be just what 1996you’re looking for. These are: 1997 1998‘gnu’ 1999 Coding style blessed by the Free Software Foundation for C code in 2000 GNU programs. 2001 2002‘k&r’ 2003 The classic Kernighan and Ritchie style for C code. If you’re 2004 looking for the style used in the 2nd edition of their book “The C 2005 Programming Language”, then check out the ‘stroustrup’ style. 2006 2007‘bsd’ 2008 Also known as “Allman style” after Eric Allman. 2009 2010‘whitesmith’ 2011 Popularized by the examples that came with Whitesmiths C, an early 2012 commercial C compiler. 2013 2014‘stroustrup’ 2015 The classic Stroustrup style for C++ code. 2016 2017‘ellemtel’ 2018 Popular C++ coding standards as defined by “Programming in C++, 2019 Rules and Recommendations,” Erik Nyquist and Mats Henricson, 2020 Ellemtel(1). 2021 2022‘linux’ 2023 C coding standard for Linux (the kernel). 2024 2025‘python’ 2026 C coding standard for Python extension modules(2). 2027 2028‘java’ 2029 The style for editing Java code. Note that the default value for 2030 ‘c-default-style’ installs this style when you enter ‘java-mode’. 2031 2032‘awk’ 2033 The style for editing AWK code. Note that the default value for 2034 ‘c-default-style’ installs this style when you enter ‘awk-mode’. 2035 2036‘user’ 2037 This is a special style created by you. It consists of the factory 2038 defaults for all the style variables as modified by the 2039 customizations you do either with the Customization interface or by 2040 writing ‘setq’s and ‘c-set-offset’s at the top level of your 2041 ‘.emacs’ file (*note Config Basics::). The style system creates 2042 this style as part of its initialization and doesn’t modify it 2043 afterwards. 2044 2045 ---------- Footnotes ---------- 2046 2047 (1) This document is available at 2048<https://www.doc.ic.ac.uk/lab/cplus/c++.rules/> among other places. 2049 2050 (2) Python is a high level scripting language with a C/C++ foreign 2051function interface. For more information, see 2052<https://www.python.org/>. 2053 2054 2055File: ccmode.info, Node: Choosing a Style, Next: Adding Styles, Prev: Built-in Styles, Up: Styles 2056 20576.3.2 Choosing a Style 2058---------------------- 2059 2060When you create a new buffer, its style will be set from 2061‘c-default-style’. The factory default is the style ‘gnu’, except in 2062Java and AWK modes where it’s ‘java’ and ‘awk’. 2063 2064 Remember that if you set a style variable with the Customization 2065interface or at the top level of your ‘.emacs’ file before the style 2066system is initialized (*note Config Basics::), this setting will 2067override the one that the style system would have given the variable. 2068 2069 To set a buffer’s style interactively, use the command ‘C-c .’ (*note 2070Other Commands::). To set it from a file’s local variable list, *note 2071File Styles::. 2072 2073 -- User Option: c-default-style 2074 This variable specifies which style to install by default in new 2075 buffers. It takes either a style name string, or an association 2076 list of major mode symbols to style names: 2077 2078 1. When ‘c-default-style’ is a string, it must be an existing 2079 style name. This style is then used for all modes. 2080 2081 2. When ‘c-default-style’ is an association list, the mode 2082 language is looked up to find a style name string. 2083 2084 3. If ‘c-default-style’ is an association list where the mode 2085 language mode isn’t found then the special symbol ‘other’ is 2086 looked up. If it’s found then the associated style is used. 2087 2088 4. If ‘other’ is not found then the ‘gnu’ style is used. 2089 2090 In all cases, the style described in ‘c-default-style’ is installed 2091 _before_ the language hooks are run, so you can always override 2092 this setting by including an explicit call to ‘c-set-style’ in your 2093 language mode hook, or in ‘c-mode-common-hook’. 2094 2095 The standard value of ‘c-default-style’ is 2096 ‘((java-mode . "java") (awk-mode . "awk") (other . "gnu"))’. 2097 2098 -- Variable: c-indentation-style 2099 This variable always contains the buffer’s current style name, as a 2100 string. 2101 2102 2103File: ccmode.info, Node: Adding Styles, Next: Guessing the Style, Prev: Choosing a Style, Up: Styles 2104 21056.3.3 Adding and Amending Styles 2106-------------------------------- 2107 2108If none of the built-in styles is appropriate, you’ll probably want to 2109create a new “style definition”, possibly based on an existing style. 2110To do this, put the new style’s settings into a list with the following 2111format; the list can then be passed as an argument to the function 2112‘c-add-style’. You can see an example of a style definition in *note 2113Sample Init File::. 2114 2115Structure of a Style Definition List 2116 ([BASE-STYLE] [(VARIABLE . VALUE) ...]) 2117 2118 Optional BASE-STYLE, if present, must be a string which is the name 2119 of the “base style” from which this style inherits. At most one 2120 BASE-STYLE is allowed in a style definition. If BASE-STYLE is not 2121 specified, the style inherits from the table of factory default 2122 values(1) instead. All styles eventually inherit from this 2123 internal table. Style loops generate errors. The list of 2124 pre-existing styles can be seen in *note Built-in Styles::. 2125 2126 The dotted pairs (VARIABLE . VALUE) each consist of a variable and 2127 the value it is to be set to when the style is later activated.(2) 2128 The variable can be either a CC Mode style variable or an arbitrary 2129 Emacs variable. In the latter case, it is _not_ made buffer-local 2130 by the CC Mode style system. 2131 2132 Two variables are treated specially in the dotted pair list: 2133 2134 ‘c-offsets-alist’ 2135 The value is in turn a list of dotted pairs of the form 2136 2137 (SYNTACTIC-SYMBOL . OFFSET) 2138 2139 as described in *note c-offsets-alist::. These are passed to 2140 ‘c-set-offset’ so there is no need to set every syntactic 2141 symbol in your style, only those that are different from the 2142 inherited style. 2143 2144 ‘c-special-indent-hook’ 2145 The value is added to ‘c-special-indent-hook’ using 2146 ‘add-hook’, so any functions already on it are kept. If the 2147 value is a list, each element of the list is added with 2148 ‘add-hook’. 2149 2150 Styles are kept in the ‘c-style-alist’ variable, but you should never 2151modify this variable directly. Instead, CC Mode provides the function 2152‘c-add-style’ for this purpose. 2153 2154 -- Function: c-add-style stylename description &optional set-p 2155 Add or update a style called STYLENAME, a string. DESCRIPTION is 2156 the new style definition in the form described above. If STYLENAME 2157 already exists in ‘c-style-alist’ then it is replaced by 2158 DESCRIPTION. (Note, this replacement is total. The old style is 2159 _not_ merged into the new one.) Otherwise, a new style is added. 2160 2161 If the optional SET-P is non-‘nil’ then the new style is applied to 2162 the current buffer as well. The use of this facility is deprecated 2163 and it might be removed from CC Mode in a future release. You 2164 should use ‘c-set-style’ instead. 2165 2166 The sample ‘.emacs’ file provides a concrete example of how a new 2167 style can be added and automatically set. *Note Sample Init 2168 File::. 2169 2170 -- Variable: c-style-alist 2171 This is the variable that holds the definitions for the styles. It 2172 should not be changed directly; use ‘c-add-style’ instead. 2173 2174 ---------- Footnotes ---------- 2175 2176 (1) This table is stored internally in the variable c-fallback-style. 2177 2178 (2) Note that if the variable has been given a value by the 2179Customization interface or a ‘setq’ at the top level of your ‘.emacs’, 2180this value will override the one the style system tries to give it. 2181*Note Config Basics::. 2182 2183 2184File: ccmode.info, Node: Guessing the Style, Next: File Styles, Prev: Adding Styles, Up: Styles 2185 21866.3.4 Guessing the Style 2187------------------------ 2188 2189Instead of specifying a style, you can get CC Mode to “guess” your style 2190by examining an already formatted code buffer. CC Mode then determines 2191the “most frequent” offset (*note c-offsets-alist::) for each of the 2192syntactic symbols (*note Indentation Engine Basics::) encountered in the 2193buffer, and the “most frequent” value of c-basic-offset (*note 2194Customizing Indentation::), then merges the current style with these 2195“guesses” to form a new style. This combined style is known as the 2196“guessed style”. 2197 2198 To do this, call ‘c-guess’ (or one of the other 5 guessing commands) 2199on your sample buffer. The analysis of your code may take some time. 2200 2201 You can then set the guessed style in any CC Mode buffer with 2202‘c-guess-install’. You can display the style with ‘c-guess-view’, and 2203preserve it by copying it into your ‘.emacs’ for future use, preferably 2204after editing it. 2205 2206‘M-x c-guess-no-install’ 2207‘M-x c-guess-buffer-no-install’ 2208‘M-x c-guess-region-no-install’ 2209 These commands analyze a part of the current buffer and guess the 2210 style from it. 2211 2212 The part of the buffer examined is either the region 2213 (‘c-guess-region-no-install’), the entire buffer 2214 (‘c-guess-buffer-no-install’), or the first ‘c-guess-region-max’ 2215 bytes (‘c-guess-no-install’). 2216 2217 Each of these commands can be given an optional prefix argument. 2218 This instructs CC Mode to combine the new guesses with the current 2219 guesses before forming the guessed style. 2220 2221‘M-x c-guess’ 2222‘M-x c-guess-buffer’ 2223‘M-x c-guess-region’ 2224 These commands analyze a part of the current buffer, guess the 2225 style from it, then install the guessed style on the buffer. The 2226 guessed style is given a name based on the buffer’s absolute file 2227 name, and you can then set this style on any CC Mode buffer with 2228 ‘C-c .’. 2229 2230 The part of the buffer examined is either the region 2231 (‘c-guess-region’), the entire buffer (‘c-guess-buffer’), or the 2232 first ‘c-guess-region-max’ bytes (‘c-guess’). 2233 2234 Each of these commands can be given an optional prefix argument. 2235 This instructs CC Mode to combine the new guesses with the current 2236 guesses before forming the guessed style. 2237 2238 -- User Option: c-guess-region-max 2239 This variable, default 50000, is the size in bytes of the buffer 2240 portion examined by c-guess and c-guess-no-install. If set to 2241 ‘nil’, the entire buffer is examined. 2242 2243 -- User Option: c-guess-offset-threshold 2244 This variable, default 10, is the maximum offset, either outwards 2245 or inwards, which will be taken into account by the analysis 2246 process. Any offset bigger than this will be ignored. For no 2247 limit, set this variable to a large number. 2248 2249‘M-x c-guess-install’ 2250 2251 Set the current buffer’s style to the guessed style. This prompts 2252 you to enter an optional new style name to give to the guessed 2253 style. By default, this name is based on the buffer’s absolute 2254 file name. You can then use this style like any other. 2255 2256‘M-x c-guess-view’ 2257 Display the most recently guessed style in a temporary buffer. 2258 This display is in the form of a ‘c-add-style’ form (*note Adding 2259 Styles::) which can be easily copied to your ‘.emacs’. You will 2260 probably want to edit it first. 2261 2262 The display of the guessed style contains these elements: 2263 2264 Placeholder Name 2265 You should replace this with a style name of your own. 2266 Parent Style 2267 The style current when the guessing began, from which the 2268 guessed style inherits (*note Config Basics::) the settings 2269 which weren’t guessed. 2270 Guessed Offsets 2271 These are the core result of the guessing process. Each of 2272 them is marked by a comment. 2273 Inherited Offsets 2274 These are syntactic offsets which have been taken over from 2275 the parent style. To avoid possible future conflicts, you 2276 should remove either these offsets or the parent style name. 2277 2278 2279File: ccmode.info, Node: File Styles, Prev: Guessing the Style, Up: Styles 2280 22816.3.5 File Styles 2282----------------- 2283 2284The Emacs manual describes how you can customize certain variables on a 2285per-file basis by including a “file local variable” block at the end of 2286the file (*note Local Variables in Files: (emacs)File Variables.). 2287 2288 So far, you’ve only seen a functional interface for setting styles in 2289CC Mode, and this can’t be used here. CC Mode fills the gap by 2290providing two variables for use in a file’s local variable list. Don’t 2291use them anywhere else! These allow you to customize the style on a 2292per-file basis: 2293 2294 -- Variable: c-file-style 2295 Set this variable to a style name string in the Local Variables 2296 list. From now on, when you visit the file, CC Mode will 2297 automatically set the file’s style to this one using ‘c-set-style’. 2298 2299 -- Variable: c-file-offsets 2300 Set this variable (in the Local Variables list) to an association 2301 list of the same format as ‘c-offsets-alist’. From now on, when 2302 you visit the file, CC Mode will automatically institute these 2303 offsets using ‘c-set-offset’. 2304 2305 Note that file style settings (i.e., ‘c-file-style’) are applied 2306before file offset settings (i.e., ‘c-file-offsets’)(1). 2307 2308 If you set any variable by the file local variables mechanism, that 2309setting takes priority over all other settings, even those in your mode 2310hooks (*note CC Hooks::). Any individual setting of a variable will 2311override one made through ‘c-file-style’ or ‘c-file-offsets’. 2312 2313 ---------- Footnotes ---------- 2314 2315 (1) Also, if either of these are set in a file’s local variable 2316section, all the style variable values are made local to that buffer, 2317even if ‘c-style-variables-are-local-p’ is ‘nil’. Since this variable 2318is virtually always non-‘nil’ anyhow, you’re unlikely to notice this 2319effect. 2320 2321 2322File: ccmode.info, Node: Custom Filling and Breaking, Next: Custom Auto-newlines, Prev: Config Basics, Up: Top 2323 23247 Customizing Filling and Line Breaking 2325*************************************** 2326 2327Since there’s a lot of normal text in comments and string literals, CC 2328Mode provides features to edit these like in text mode. It does this by 2329hooking in on the different line breaking functions and tuning relevant 2330variables as necessary. 2331 2332 To make Emacs recognize comments and treat text in them as normal 2333paragraphs, CC Mode makes several standard variables(1) buffer-local and 2334modifies them according to the language syntax and the comment line 2335prefix. 2336 2337 -- User Option: c-comment-prefix-regexp 2338 This style variable contains the regexp used to recognize the 2339 “comment line prefix”, which is the line decoration that starts 2340 every line in a comment. The variable is either the comment line 2341 prefix itself, or (more usually) an association list with different 2342 values for different languages. The symbol for the major mode is 2343 looked up in the alist to get the regexp for the language, and if 2344 it isn’t found then the special symbol ‘other’ is looked up 2345 instead. 2346 2347 When a comment line gets divided by ‘M-j’ or the like, CC Mode 2348 inserts the comment line prefix from a neighboring line at the 2349 start of the new line. The default value of 2350 c-comment-prefix-regexp is ‘//+\\|\\**’, which matches C++ style 2351 line comments like 2352 2353 // blah blah 2354 2355 with two or more slashes in front of them, and the second and 2356 subsequent lines of C style block comments like 2357 2358 /* 2359 * blah blah 2360 */ 2361 2362 with zero or more stars at the beginning of every line. If you 2363 change this variable, please make sure it still matches the comment 2364 starter (i.e., ‘//’) of line comments _and_ the line prefix inside 2365 block comments. 2366 2367 Also note that since CC Mode uses the value of 2368 ‘c-comment-prefix-regexp’ to set up several other variables at mode 2369 initialization, there won’t be any effect if you just change it 2370 inside a CC Mode buffer. You need to call the command 2371 ‘c-setup-paragraph-variables’ too, to update those other variables. 2372 That’s also the case if you modify ‘c-comment-prefix-regexp’ in a 2373 mode hook, since CC Mode will already have set up these variables 2374 before calling the hook. 2375 2376 In comments, CC Mode uses ‘c-comment-prefix-regexp’ to adapt the line 2377prefix from the other lines in the comment. 2378 2379 CC Mode uses adaptive fill mode (*note (emacs)Adaptive Fill::) to 2380make Emacs correctly keep the line prefix when filling paragraphs. That 2381also makes Emacs preserve the text indentation _inside_ the comment line 2382prefix. E.g., in the following comment, both paragraphs will be filled 2383with the left margins of the texts kept intact: 2384 2385 /* Make a balanced b-tree of the nodes in the incoming 2386 * stream. But, to quote the famous words of Donald E. 2387 * Knuth, 2388 * 2389 * Beware of bugs in the above code; I have only 2390 * proved it correct, not tried it. 2391 */ 2392 2393 It’s also possible to use other adaptive filling packages, notably 2394Kyle E. Jones’ Filladapt package(2), which handles things like bulleted 2395lists nicely. There’s a convenience function ‘c-setup-filladapt’ that 2396tunes the relevant variables in Filladapt for use in CC Mode. Call it 2397from a mode hook, e.g., with something like this in your ‘.emacs’: 2398 2399 (defun my-c-mode-common-hook () 2400 (c-setup-filladapt) 2401 (filladapt-mode 1)) 2402 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) 2403 2404 -- User Option: c-block-comment-prefix 2405 Normally the comment line prefix inserted for a new line inside a 2406 comment is deduced from other lines in it. However there’s one 2407 situation when there’s no hint about what the prefix should look 2408 like, namely when a block comment is broken for the first time. 2409 This style variable(3) is used then as the comment prefix. It 2410 defaults to ‘* ’(4), which makes a comment 2411 2412 /* Got O(n^2) here, which is a Bad Thing. */ 2413 2414 break into 2415 2416 /* Got O(n^2) here, which 2417 * is a Bad Thing. */ 2418 2419 Note that it won’t work to adjust the indentation by putting 2420 leading spaces in ‘c-block-comment-prefix’, since CC Mode still 2421 uses the normal indentation engine to indent the line. Thus, the 2422 right way to fix the indentation is by customizing the ‘c’ 2423 syntactic symbol. It defaults to ‘c-lineup-C-comments’, which 2424 handles the indentation of most common comment styles, see *note 2425 Line-Up Functions::. 2426 2427 -- User Option: c-ignore-auto-fill 2428 When auto fill mode is enabled, CC Mode can selectively ignore it 2429 depending on the context the line break would occur in, e.g., to 2430 never break a line automatically inside a string literal. This 2431 variable takes a list of symbols for the different contexts where 2432 auto-filling never should occur: 2433 2434 ‘string’ 2435 Inside a string or character literal. 2436 ‘c’ 2437 Inside a C style block comment. 2438 ‘c++’ 2439 Inside a C++ style line comment. 2440 ‘cpp’ 2441 Inside a preprocessor directive. 2442 ‘code’ 2443 Anywhere else, i.e., in normal code. 2444 2445 By default, ‘c-ignore-auto-fill’ is set to ‘(string cpp code)’, 2446 which means that when auto-fill mode is activated, auto-filling 2447 only occurs in comments. In literals, it’s often desirable to have 2448 explicit control over newlines. In preprocessor directives, the 2449 necessary ‘\’ escape character before the newline is not 2450 automatically inserted, so an automatic line break would produce 2451 invalid code. In normal code, line breaks are normally dictated by 2452 some logical structure in the code rather than the last whitespace 2453 character, so automatic line breaks there will produce poor results 2454 in the current implementation. 2455 2456 If inside a comment and ‘comment-multi-line’ (*note (emacs)Auto 2457Fill:: is non-‘nil’, the indentation and line prefix are preserved. If 2458inside a comment and ‘comment-multi-line’ is ‘nil’, a new comment of the 2459same type is started on the next line and indented as appropriate for 2460comments. 2461 2462 Note that CC Mode sets ‘comment-multi-line’ to ‘t’ at startup. The 2463reason is that ‘M-j’ could otherwise produce sequences of single line 2464block comments for texts that should logically be treated as one 2465comment, and the rest of the paragraph handling code (e.g., ‘M-q’ and 2466‘M-a’) can’t cope with that, which would lead to inconsistent behavior. 2467 2468 ---------- Footnotes ---------- 2469 2470 (1) ‘comment-start’, ‘comment-end’, ‘comment-start-skip’, 2471‘paragraph-start’, ‘paragraph-separate’, ‘paragraph-ignore-fill-prefix’, 2472‘adaptive-fill-mode’, ‘adaptive-fill-regexp’, and 2473‘adaptive-fill-first-line-regexp’. 2474 2475 (2) It’s available from <http://www.wonderworks.com/>. As of version 24762.12, it does however lack a feature that makes it work suboptimally 2477when ‘c-comment-prefix-regexp’ matches the empty string (which it does 2478by default). A patch for that is available from the CC Mode web site. 2479 2480 (3) In versions before 5.26, this variable was called 2481‘c-comment-continuation-stars’. As a compatibility measure, CC Mode 2482still uses the value on that variable if it’s set. 2483 2484 (4) Actually, this default setting of ‘c-block-comment-prefix’ 2485typically gets overridden by the default style ‘gnu’, which sets it to 2486blank. You can see the line splitting effect described here by setting 2487a different style, e.g., ‘k&r’ *Note Choosing a Style::. 2488 2489 2490File: ccmode.info, Node: Custom Auto-newlines, Next: Clean-ups, Prev: Custom Filling and Breaking, Up: Top 2491 24928 Customizing Auto-newlines 2493*************************** 2494 2495CC Mode determines whether to insert auto-newlines in two basically 2496different ways, depending on the character just typed: 2497 2498Braces and Colons 2499 CC Mode first determines the syntactic context of the brace or 2500 colon (*note Syntactic Symbols::), then looks for a corresponding 2501 element in an alist. This element specifies where to put newlines: 2502 this is any combination of before and after the brace or colon. If 2503 no alist element is found, newlines are inserted both before and 2504 after a brace, but none are inserted around a colon. See *note 2505 Hanging Braces:: and *note Hanging Colons::. 2506 2507Semicolons and Commas 2508 The variable ‘c-hanging-semi&comma-criteria’ contains a list of 2509 functions which determine whether to insert a newline after a newly 2510 typed semicolon or comma. *Note Hanging Semicolons and Commas::. 2511 2512 The names of these configuration variables contain ‘hanging’ because 2513they let you “hang” the pertinent characters. A character which 2514introduces a C construct is said to “hang on the right” when it appears 2515at the end of a line after other code, being separated by a line break 2516from the construct it introduces, like the opening brace in: 2517 2518 while (i < MAX) { 2519 total += entry[i]; 2520 entry [i++] = 0; 2521 } 2522 2523A character “hangs on the left” when it appears at the start of the line 2524after the construct it closes off, like the above closing brace. 2525 2526 The next chapter, “Clean-ups”, describes how to configure CC Mode to 2527remove these automatically added newlines in certain specific 2528circumstances. *Note Clean-ups::. 2529 2530* Menu: 2531 2532* Hanging Braces:: 2533* Hanging Colons:: 2534* Hanging Semicolons and Commas:: 2535 2536 2537File: ccmode.info, Node: Hanging Braces, Next: Hanging Colons, Prev: Custom Auto-newlines, Up: Custom Auto-newlines 2538 25398.1 Hanging Braces 2540================== 2541 2542To specify which kinds of braces you want auto-newlines put around, you 2543set the style variable ‘c-hanging-braces-alist’. Its structure and 2544semantics are described in this section. Details of how to set it up, 2545and its relationship to CC Mode’s style system are given in *note Style 2546Variables::. 2547 2548 Say you wanted an auto-newline after (but not before) the following 2549‘{’: 2550 2551 if (foo < 17) { 2552 2553First you need to find the “syntactic context” of the brace—type a <RET> 2554before the brace to get it on a line of its own(1), then type ‘C-c C-s’. 2555That will tell you something like: 2556 2557 ((substatement-open 1061)) 2558 2559So here you need to put the entry ‘(substatement-open . (after))’ into 2560‘c-hanging-braces-alist’. 2561 2562 If you don’t want any auto-newlines for a particular syntactic 2563symbol, put this into ‘c-hanging-braces-alist’: 2564 2565 (brace-entry-open) 2566 2567 If some brace syntactic symbol is not in ‘c-hanging-brace-alist’, its 2568entry is taken by default as ‘(before after)’—insert a newline both 2569before and after the brace. In place of a “before/after” list you can 2570specify a function in this alist—this is useful when the auto newlines 2571depend on the code around the brace. 2572 2573 -- User Option: c-hanging-braces-alist 2574 2575 This variable is an association list which maps syntactic symbols 2576 to lists of places to insert a newline. *Note (elisp)Association 2577 Lists::. The key of each element is the syntactic symbol, the 2578 associated value is either ‘nil’, a list, or a function. 2579 2580 The Key: the syntactic symbol 2581 The syntactic symbols that are useful as keys in this list are 2582 ‘brace-list-intro’, ‘statement-cont’, ‘inexpr-class-open’, 2583 ‘inexpr-class-close’, and all the ‘*-open’ and ‘*-close’ 2584 symbols. *Note Syntactic Symbols::, for a more detailed 2585 description of these syntactic symbols, except for 2586 ‘inexpr-class-open’ and ‘inexpr-class-close’, which aren’t 2587 actual syntactic symbols. Elements with any other value as a 2588 key get ignored. 2589 2590 The braces of anonymous inner classes in Java are given the 2591 special symbols ‘inexpr-class-open’ and ‘inexpr-class-close’, 2592 so that they can be distinguished from the braces of normal 2593 classes(2). 2594 2595 Note that the aggregate constructs in Pike mode, ‘({’, ‘})’, 2596 ‘([’, ‘])’, and ‘(<’, ‘>)’, do not count as brace lists in 2597 this regard, even though they do for normal indentation 2598 purposes. It’s currently not possible to set automatic 2599 newlines on these constructs. 2600 2601 The associated value: the “ACTION” list or function 2602 The value associated with each syntactic symbol in this 2603 association list is called an ACTION, which can be either a 2604 list or a function which returns a list. *Note Custom 2605 Braces::, for how to use a function as a brace hanging ACTION. 2606 2607 The list ACTION (or the list returned by ACTION when it’s a 2608 function) contains some combination of the symbols ‘before’ 2609 and ‘after’, directing CC Mode where to put newlines in 2610 relationship to the brace being inserted. Thus, if the list 2611 contains only the symbol ‘after’, then the brace hangs on the 2612 right side of the line, as in: 2613 2614 // here, open braces always 'hang' 2615 void spam( int i ) { 2616 if( i == 7 ) { 2617 dosomething(i); 2618 } 2619 } 2620 2621 When the list contains both ‘after’ and ‘before’, the braces 2622 will appear on a line by themselves, as shown by the close 2623 braces in the above example. The list can also be empty, in 2624 which case newlines are added neither before nor after the 2625 brace. 2626 2627 If a syntactic symbol is missing entirely from 2628 ‘c-hanging-braces-alist’, it’s treated in the same way as an ACTION 2629 with a list containing ‘before’ and ‘after’, so that braces by 2630 default end up on their own line. 2631 2632 For example, the default value of ‘c-hanging-braces-alist’ is: 2633 2634 ((brace-list-open) 2635 (brace-entry-open) 2636 (statement-cont) 2637 (substatement-open after) 2638 (block-close . c-snug-do-while) 2639 (extern-lang-open after) 2640 (namespace-open after) 2641 (module-open after) 2642 (composition-open after) 2643 (inexpr-class-open after) 2644 (inexpr-class-close before)) 2645 2646 which says that ‘brace-list-open’, ‘brace-entry-open’ and 2647 ‘statement-cont’(3) braces should both hang on the right side and 2648 allow subsequent text to follow on the same line as the brace. 2649 Also, ‘substatement-open’, ‘extern-lang-open’, and 2650 ‘inexpr-class-open’ braces should hang on the right side, but 2651 subsequent text should follow on the next line. The opposite holds 2652 for ‘inexpr-class-close’ braces; they won’t hang, but the following 2653 text continues on the same line. Here, in the ‘block-close’ entry, 2654 you also see an example of using a function as an ACTION. In all 2655 other cases, braces are put on a line by themselves. 2656 2657* Menu: 2658 2659* Custom Braces:: 2660 2661 ---------- Footnotes ---------- 2662 2663 (1) Also insert a ‘\’ at the end of the previous line if you’re in 2664AWK Mode. 2665 2666 (2) The braces of anonymous classes produce a combination of 2667‘inexpr-class’, and ‘class-open’ or ‘class-close’ in normal indentation 2668analysis. 2669 2670 (3) Brace lists inside statements, such as initializers for static 2671array variables inside functions in C, are recognized as 2672‘statement-cont’. All normal substatement blocks are recognized with 2673other symbols. 2674 2675 2676File: ccmode.info, Node: Custom Braces, Prev: Hanging Braces, Up: Hanging Braces 2677 26788.1.1 Custom Brace Hanging 2679-------------------------- 2680 2681Syntactic symbols aren’t the only place where you can customize CC Mode 2682with the lisp equivalent of callback functions. Remember that ACTIONs 2683are usually a list containing some combination of the symbols ‘before’ 2684and ‘after’ (*note Hanging Braces::). For more flexibility, you can 2685instead specify brace “hanginess” by giving a syntactic symbol an 2686“action function” in ‘c-hanging-braces-alist’; this function determines 2687the “hanginess” of a brace, usually by looking at the code near it. 2688 2689 An action function is called with two arguments: the syntactic symbol 2690for the brace (e.g., ‘substatement-open’), and the buffer position where 2691the brace has been inserted. Point is undefined on entry to an action 2692function, but the function must preserve it (e.g., by using 2693‘save-excursion’). The return value should be a list containing some 2694combination of ‘before’ and ‘after’, including neither of them (i.e., 2695‘nil’). 2696 2697 -- Variable: c-syntactic-context 2698 During the call to the indentation or brace hanging ACTION 2699 function, this variable is bound to the full syntactic analysis 2700 list. This might be, for example, ‘((block-close 73))’. Don’t 2701 ever give ‘c-syntactic-context’ a value yourself—this would disrupt 2702 the proper functioning of CC Mode. 2703 2704 This variable is also bound in three other circumstances: (i) when 2705 calling a c-hanging-semi&comma-criteria function (*note Hanging 2706 Semicolons and Commas::); (ii) when calling a line-up function 2707 (*note Custom Line-Up::); (iii) when calling a 2708 c-special-indent-hook function (*note Other Indentation::). 2709 2710 As an example, CC Mode itself uses this feature to dynamically 2711determine the hanginess of braces which close “do-while” constructs: 2712 2713 void do_list( int count, char** atleast_one_string ) 2714 { 2715 int i=0; 2716 do { 2717 handle_string( atleast_one_string[i] ); 2718 i++; 2719 } while( i < count ); 2720 } 2721 2722 CC Mode assigns the ‘block-close’ syntactic symbol to the brace that 2723closes the ‘do’ construct, and normally we’d like the line that follows 2724a ‘block-close’ brace to begin on a separate line. However, with 2725“do-while” constructs, we want the ‘while’ clause to follow the closing 2726brace. To do this, we associate the ‘block-close’ symbol with the 2727ACTION function ‘c-snug-do-while’: 2728 2729 (defun c-snug-do-while (syntax pos) 2730 "Dynamically calculate brace hanginess for do-while statements." 2731 (save-excursion 2732 (let (langelem) 2733 (if (and (eq syntax 'block-close) 2734 (setq langelem (assq 'block-close c-syntactic-context)) 2735 (progn (goto-char (cdr langelem)) 2736 (if (= (following-char) ?{) 2737 (forward-sexp -1)) 2738 (looking-at "\\<do\\>[^_]"))) 2739 '(before) 2740 '(before after))))) 2741 2742 This function simply looks to see if the brace closes a “do-while” 2743clause and if so, returns the list ‘(before)’ indicating that a newline 2744should be inserted before the brace, but not after it. In all other 2745cases, it returns the list ‘(before after)’ so that the brace appears on 2746a line by itself. 2747 2748 2749File: ccmode.info, Node: Hanging Colons, Next: Hanging Semicolons and Commas, Prev: Hanging Braces, Up: Custom Auto-newlines 2750 27518.2 Hanging Colons 2752================== 2753 2754Using a mechanism similar to brace hanging (*note Hanging Braces::), 2755colons can also be made to hang using the style variable 2756‘c-hanging-colons-alist’: when a colon is typed, CC Mode determines its 2757syntactic context, looks this up in the alist ‘c-changing-colons-alist’ 2758and inserts up to two newlines accordingly. Here, however, If CC Mode 2759fails to find an entry for a syntactic symbol in the alist, no newlines 2760are inserted around the newly typed colon. 2761 2762 -- User Option: c-hanging-colons-alist 2763 2764 The Key: the syntactic symbol 2765 The syntactic symbols appropriate as keys in this association 2766 list are: ‘case-label’, ‘label’, ‘access-label’, 2767 ‘member-init-intro’, and ‘inher-intro’. *Note Syntactic 2768 Symbols::. Elements with any other value as a key get 2769 ignored. 2770 2771 The associated value: the “ACTION” list 2772 The ACTION here is simply a list containing a combination of 2773 the symbols ‘before’ and ‘after’. Unlike in 2774 ‘c-hanging-braces-alist’, functions as ACTIONS are not 2775 supported; there doesn’t seem to be any need for them. 2776 2777 In C++, double-colons are used as a scope operator but because these 2778colons always appear right next to each other, newlines before and after 2779them are controlled by a different mechanism, called “clean-ups” in CC 2780Mode. *Note Clean-ups::, for details. 2781 2782 2783File: ccmode.info, Node: Hanging Semicolons and Commas, Prev: Hanging Colons, Up: Custom Auto-newlines 2784 27858.3 Hanging Semicolons and Commas 2786================================= 2787 2788 -- User Option: c-hanging-semi&comma-criteria 2789 This style variable takes a list of functions; these get called 2790 when you type a semicolon or comma. The functions are called in 2791 order without arguments. When these functions are entered, point 2792 is just after the newly inserted ‘;’ or ‘,’ and they must preserve 2793 point (e.g., by using ‘save-excursion’). During the call, the 2794 variable ‘c-syntactic-context’ is bound to the syntactic context of 2795 the current line(1) *note Custom Braces::. These functions don’t 2796 insert newlines themselves, rather they direct CC Mode whether or 2797 not to do so. They should return one of the following values: 2798 2799 ‘t’ 2800 A newline is to be inserted after the ‘;’ or ‘,’, and no more 2801 functions from the list are to be called. 2802 ‘stop’ 2803 No more functions from the list are to be called, and no 2804 newline is to be inserted. 2805 ‘nil’ 2806 No determination has been made, and the next function in the 2807 list is to be called. 2808 2809 Note that auto-newlines are never inserted _before_ a semicolon or 2810 comma. If every function in the list is called without a 2811 determination being made, then no newline is added. 2812 2813 In AWK mode, this variable is set by default to ‘nil’. In the 2814 other modes, the default value is a list containing a single 2815 function, ‘c-semi&comma-inside-parenlist’. This inserts newlines 2816 after all semicolons, apart from those separating ‘for’-clause 2817 statements. 2818 2819 -- Function: c-semi&comma-no-newlines-before-nonblanks 2820 This is an example of a criteria function, provided by CC Mode. It 2821 prevents newlines from being inserted after semicolons when there 2822 is a non-blank following line. Otherwise, it makes no 2823 determination. To use, add this function to the front of the 2824 ‘c-hanging-semi&comma-criteria’ list. 2825 2826 (defun c-semi&comma-no-newlines-before-nonblanks () 2827 (save-excursion 2828 (if (and (= (c-last-command-char) ?\;) 2829 (zerop (forward-line 1)) 2830 (bolp) ; forward-line has funny behavior at eob. 2831 (not (looking-at "^[ \t]*$"))) 2832 'stop 2833 nil))) 2834 2835 -- Function: c-semi&comma-inside-parenlist 2836 -- Function: c-semi&comma-no-newlines-for-oneline-inliners 2837 The function ‘c-semi&comma-inside-parenlist’ is what prevents 2838 newlines from being inserted inside the parenthesis list of ‘for’ 2839 statements. In addition to 2840 ‘c-semi&comma-no-newlines-before-nonblanks’ described above, CC 2841 Mode also comes with the criteria function 2842 ‘c-semi&comma-no-newlines-for-oneline-inliners’, which suppresses 2843 newlines after semicolons inside one-line inline method definitions 2844 (e.g., in C++ or Java). 2845 2846 ---------- Footnotes ---------- 2847 2848 (1) This was first introduced in CC Mode 5.31. 2849 2850 2851File: ccmode.info, Node: Clean-ups, Next: Indentation Engine Basics, Prev: Custom Auto-newlines, Up: Top 2852 28539 Clean-ups 2854*********** 2855 2856“Clean-ups” are mechanisms which remove (or exceptionally, add) 2857whitespace in specific circumstances and are complementary to colon and 2858brace hanging. You enable a clean-up by adding its symbol into 2859‘c-cleanup-list’, e.g., like this: 2860 2861 (add-to-list 'c-cleanup-list 'space-before-funcall) 2862 2863 On the surface, it would seem that clean-ups overlap the 2864functionality provided by the ‘c-hanging-*-alist’ variables. Clean-ups, 2865however, are used to adjust code “after-the-fact”, i.e., to adjust the 2866whitespace in constructs later than when they were typed. 2867 2868 Most of the clean-ups remove automatically inserted newlines, and are 2869only active when auto-newline minor mode is turned on. Others will work 2870all the time. Note that clean-ups are only performed when there is 2871nothing but whitespace appearing between the individual components of 2872the construct, and (apart from ‘comment-close-slash’) when the construct 2873does not occur within a literal (*note Auto-newlines::). 2874 2875 -- User Option: c-cleanup-list 2876 2877 You configure CC Mode’s clean-ups by setting the style variable 2878 ‘c-cleanup-list’, which is a list of clean-up symbols. By default, 2879 CC Mode cleans up only the ‘scope-operator’ construct, which is 2880 necessary for proper C++ support. 2881 2882 These are the clean-ups that are only active when electric and 2883auto-newline minor modes are enabled: 2884 2885‘brace-else-brace’ 2886 Clean up ‘} else {’ constructs by placing the entire construct on a 2887 single line. Clean up occurs when the open brace after the ‘else’ 2888 is typed. So for example, this: 2889 2890 void spam(int i) 2891 { 2892 if( i==7 ) { 2893 dosomething(); 2894 } 2895 else 2896 { 2897 2898 appears like this after the last open brace is typed: 2899 2900 void spam(int i) 2901 { 2902 if( i==7 ) { 2903 dosomething(); 2904 } else { 2905 2906‘brace-elseif-brace’ 2907 Similar to the ‘brace-else-brace’ clean-up, but this cleans up ‘} 2908 else if (...) {’ constructs. For example: 2909 2910 void spam(int i) 2911 { 2912 if( i==7 ) { 2913 dosomething(); 2914 } 2915 else if( i==3 ) 2916 { 2917 2918 appears like this after the last open parenthesis is typed: 2919 2920 void spam(int i) 2921 { 2922 if( i==7 ) { 2923 dosomething(); 2924 } else if( 2925 2926 and like this after the last open brace is typed: 2927 2928 void spam(int i) 2929 { 2930 if( i==7 ) { 2931 dosomething(); 2932 } else if( i==3 ) { 2933 2934‘brace-catch-brace’ 2935 Analogous to ‘brace-elseif-brace’, but cleans up ‘} catch (...) {’ 2936 in C++ and Java mode. 2937 2938‘empty-defun-braces’ 2939 Clean up braces following a top-level function or class definition 2940 that contains no body. Clean up occurs when the closing brace is 2941 typed. Thus the following: 2942 2943 class Spam 2944 { 2945 } 2946 2947 is transformed into this when the close brace is typed: 2948 2949 class Spam 2950 {} 2951 2952‘defun-close-semi’ 2953 Clean up the terminating semicolon on top-level function or class 2954 definitions when they follow a close brace. Clean up occurs when 2955 the semicolon is typed. So for example, the following: 2956 2957 class Spam 2958 { 2959 ... 2960 } 2961 ; 2962 2963 is transformed into this when the semicolon is typed: 2964 2965 class Spam 2966 { 2967 ... 2968 }; 2969 2970‘list-close-comma’ 2971 Clean up commas following braces in array and aggregate 2972 initializers. Clean up occurs when the comma is typed. The space 2973 before the comma is zapped just like the space before the semicolon 2974 in ‘defun-close-semi’. 2975 2976‘scope-operator’ 2977 Clean up double colons which might designate a C++ scope operator 2978 split across multiple lines(1). Clean up occurs when the second 2979 colon is typed. You will always want ‘scope-operator’ in the 2980 ‘c-cleanup-list’ when you are editing C++ code. 2981 2982‘one-liner-defun’ 2983 Clean up a single line of code enclosed by defun braces by removing 2984 the whitespace before and after the code. The clean-up happens 2985 when the closing brace is typed. If the variable 2986 ‘c-max-one-liner-length’ is set, the cleanup is only done if the 2987 resulting line would be no longer than the value of that variable. 2988 2989 For example, consider this AWK code: 2990 2991 BEGIN { 2992 FS = "\t" # use <TAB> as a field separator 2993 } 2994 2995 It gets compacted to the following when the closing brace is typed: 2996 2997 BEGIN {FS = "\t"} # use <TAB> as a field separator 2998 2999 -- User Option: c-max-one-liner-length 3000 The maximum length of the resulting line for which the 3001 clean-up ‘one-liner-defun’ will be triggered. This length is 3002 that of the entire line, including any leading whitespace and 3003 any trailing comment. Its default value is 80. If the value 3004 is zero or ‘nil’, no limit applies. 3005 3006 The following clean-ups are always active when they occur on 3007‘c-cleanup-list’, regardless of whether Electric minor mode or 3008Auto-newline minor mode are enabled: 3009 3010‘space-before-funcall’ 3011 Insert a space between the function name and the opening 3012 parenthesis of a function call. This produces function calls in 3013 the style mandated by the GNU coding standards, e.g., 3014 ‘signal (SIGINT, SIG_IGN)’ and ‘abort ()’. Clean up occurs when 3015 the opening parenthesis is typed. This clean-up should never be 3016 active in AWK Mode, since such a space is syntactically invalid for 3017 user defined functions. 3018 3019‘compact-empty-funcall’ 3020 Clean up any space between the function name and the opening 3021 parenthesis of a function call that has no arguments. This is 3022 typically used together with ‘space-before-funcall’ if you prefer 3023 the GNU function call style for functions with arguments but think 3024 it looks ugly when it’s only an empty parenthesis pair. I.e., you 3025 will get ‘signal (SIGINT, SIG_IGN)’, but ‘abort()’. Clean up 3026 occurs when the closing parenthesis is typed. 3027 3028‘comment-close-slash’ 3029 When inside a block comment, terminate the comment when you type a 3030 slash at the beginning of a line (i.e., immediately after the 3031 comment prefix). This clean-up removes whitespace preceding the 3032 slash and if needed, inserts a star to complete the token ‘*/’. 3033 Type ‘C-q /’ in this situation if you just want a literal ‘/’ 3034 inserted. 3035 3036 ---------- Footnotes ---------- 3037 3038 (1) Certain C++ constructs introduce ambiguous situations, so 3039‘scope-operator’ clean-ups might not always be correct. This usually 3040only occurs when scoped identifiers appear in switch label tags. 3041 3042 3043File: ccmode.info, Node: Indentation Engine Basics, Next: Customizing Indentation, Prev: Clean-ups, Up: Top 3044 304510 Indentation Engine Basics 3046**************************** 3047 3048This chapter will briefly cover how CC Mode indents lines of code. It 3049is helpful to understand the indentation model being used so that you 3050will know how to customize CC Mode for your personal coding style. All 3051the details are in *note Customizing Indentation::. 3052 3053 CC Mode has an indentation engine that provides a flexible and 3054general mechanism for customizing indentation. When CC Mode indents a 3055line of code, it separates its calculations into two steps: 3056 3057 1. It analyzes the line to determine its “syntactic symbol(s)” (the 3058 kind of language construct it’s looking at) and its “anchor 3059 position” (the position earlier in the file that CC Mode will 3060 indent the line relative to). The anchor position might be the 3061 location of an opening brace in the previous line, for example. 3062 *Note Syntactic Analysis::. 3063 2. It looks up the syntactic symbol(s) in the configuration to get the 3064 corresponding “offset(s)”. The symbol ‘+’, which means “indent 3065 this line one more level” is a typical offset. CC Mode then 3066 applies these offset(s) to the anchor position, giving the 3067 indentation for the line. The different sorts of offsets are 3068 described in *note c-offsets-alist::. 3069 3070 In exceptional circumstances, the syntax directed indentation 3071described here may be a nuisance rather than a help. You can disable it 3072by setting ‘c-syntactic-indentation’ to ‘nil’. (To set the variable 3073interactively, *note Minor Modes::). 3074 3075 -- User Option: c-syntactic-indentation 3076 When this is non-‘nil’ (which it is by default), the indentation of 3077 code is done according to its syntactic structure. When it’s 3078 ‘nil’, every line is just indented to the same level as the 3079 previous one, and ‘TAB’ (‘c-indent-command’) adjusts the 3080 indentation in steps of ‘c-basic-offset’. The current style (*note 3081 Config Basics::) then has no effect on indentation, nor do any of 3082 the variables associated with indentation, not even 3083 ‘c-special-indent-hook’. 3084 3085* Menu: 3086 3087* Syntactic Analysis:: 3088* Syntactic Symbols:: 3089* Indentation Calculation:: 3090 3091 3092File: ccmode.info, Node: Syntactic Analysis, Next: Syntactic Symbols, Prev: Indentation Engine Basics, Up: Indentation Engine Basics 3093 309410.1 Syntactic Analysis 3095======================= 3096 3097The first thing CC Mode does when indenting a line of code, is to 3098analyze the line by calling ‘c-guess-basic-syntax’, determining the 3099syntactic context of the (first) construct on that line. Although this 3100function is mainly used internally, it can sometimes be useful in 3101Line-up functions (*note Custom Line-Up::) or in functions on 3102‘c-special-indent-hook’ (*note Other Indentation::). 3103 3104 -- Function: c-guess-basic-syntax 3105 Determine the syntactic context of the current line. 3106 3107 The “syntactic context” is a list of “syntactic elements”, where each 3108syntactic element in turn is a list(1) Here is a brief and typical 3109example: 3110 3111 ((defun-block-intro 1959)) 3112 3113The first thing inside each syntactic element is always a “syntactic 3114symbol”. It describes the kind of construct that was recognized, e.g., 3115‘statement’, ‘substatement’, ‘class-open’, ‘class-close’, etc. *Note 3116Syntactic Symbols::, for a complete list of currently recognized 3117syntactic symbols and their semantics. The remaining entries are 3118various data associated with the recognized construct; there might be 3119zero or more. 3120 3121 Conceptually, a line of code is always indented relative to some 3122position higher up in the buffer (typically the indentation of the 3123previous line). That position is the “anchor position” in the syntactic 3124element. If there is an entry after the syntactic symbol in the 3125syntactic element list then it’s either ‘nil’ or that anchor position. 3126 3127 Here is an example. Suppose we had the following code as the only 3128thing in a C++ buffer (2): 3129 3130 1: void swap( int& a, int& b ) 3131 2: { 3132 3: int tmp = a; 3133 4: a = b; 3134 5: b = tmp; 3135 6: } 3136 3137We can use ‘C-c C-s’ (‘c-show-syntactic-information’) to report what the 3138syntactic analysis is for the current line: 3139 3140‘C-c C-s’ (‘c-show-syntactic-information’) 3141 This command calculates the syntactic analysis of the current line 3142 and displays it in the minibuffer. The command also highlights the 3143 anchor position(s). 3144 3145 Running this command on line 4 of this example, we’d see in the echo 3146area(3): 3147 3148 ((statement 35)) 3149 3150and the ‘i’ of ‘int’ on line 3 would be highlighted. This tells us that 3151the line is a statement and it is indented relative to buffer position 315235, the highlighted position. If you were to move point to line 3 and 3153hit ‘C-c C-s’, you would see: 3154 3155 ((defun-block-intro 29)) 3156 3157This indicates that the ‘int’ line is the first statement in a top level 3158function block, and is indented relative to buffer position 29, which is 3159the brace just after the function header. 3160 3161 Here’s another example: 3162 3163 1: int add( int val, int incr, int doit ) 3164 2: { 3165 3: if( doit ) 3166 4: { 3167 5: return( val + incr ); 3168 6: } 3169 7: return( val ); 3170 8: } 3171 3172Hitting ‘C-c C-s’ on line 4 gives us: 3173 3174 ((substatement-open 46)) 3175 3176which tells us that this is a brace that _opens_ a substatement 3177block.(4) 3178 3179 Syntactic contexts can contain more than one element, and syntactic 3180elements need not have anchor positions. The most common example of 3181this is a “comment-only line”: 3182 3183 1: void draw_list( List<Drawables>& drawables ) 3184 2: { 3185 3: // call the virtual draw() method on each element in list 3186 4: for( int i=0; i < drawables.count(), ++i ) 3187 5: { 3188 6: drawables[i].draw(); 3189 7: } 3190 8: } 3191 3192Hitting ‘C-c C-s’ on line 3 of this example gives: 3193 3194 ((comment-intro) (defun-block-intro 46)) 3195 3196and you can see that the syntactic context contains two syntactic 3197elements. Notice that the first element, ‘(comment-intro)’, has no 3198anchor position. 3199 3200 ---------- Footnotes ---------- 3201 3202 (1) In CC Mode 5.28 and earlier, a syntactic element was a dotted 3203pair; the cons was the syntactic symbol and the cdr was the anchor 3204position. For compatibility’s sake, the parameter passed to a line-up 3205function still has this dotted pair form (*note Custom Line-Up::). 3206 3207 (2) The line numbers in this and future examples don’t actually 3208appear in the buffer, of course! 3209 3210 (3) With a universal argument (i.e., ‘C-u C-c C-s’) the analysis is 3211inserted into the buffer as a comment on the current line. 3212 3213 (4) A “substatement” is the line after a conditional statement, such 3214as ‘if’, ‘else’, ‘while’, ‘do’, ‘switch’, etc. A “substatement block” 3215is a brace block following one of these conditional statements. 3216 3217 3218File: ccmode.info, Node: Syntactic Symbols, Next: Indentation Calculation, Prev: Syntactic Analysis, Up: Indentation Engine Basics 3219 322010.2 Syntactic Symbols 3221====================== 3222 3223This section is a complete list of the syntactic symbols which appear in 3224the ‘c-offsets-alist’ style variable, along with brief descriptions. 3225The previous section (*note Syntactic Analysis::) states what syntactic 3226symbols are and how the indentation engine uses them. 3227 3228 More detailed descriptions of these symbols, together with snippets 3229of source code to which they apply, appear in the examples in the 3230subsections below. Note that, in the interests of brevity, the anchor 3231position associated with most syntactic symbols is _not_ specified. In 3232cases of doubt, type ‘C-c C-s’ on a pertinent line—this highlights the 3233anchor position. 3234 3235 The syntactic symbols which indicate brace constructs follow a 3236general naming convention. When a line begins with an open or close 3237brace, its syntactic symbol will contain the suffix ‘-open’ or ‘-close’ 3238respectively. The first line within the brace block construct will 3239contain the suffix ‘-block-intro’. 3240 3241 In constructs which can span several lines, a distinction is usually 3242made between the first line that introduces the construct and the lines 3243that continue it. The syntactic symbols that indicate these lines will 3244contain the suffixes ‘-intro’ or ‘-cont’ respectively. 3245 3246 The best way to understand how all this works is by looking at some 3247examples. Remember that you can see the syntax of any source code line 3248by using ‘C-c C-s’. 3249 3250‘string’ 3251 Inside a multiline string. *note Literal Symbols::. 3252‘c’ 3253 Inside a multiline C style block comment. *note Literal Symbols::. 3254‘defun-open’ 3255 Brace that opens a top-level function definition. *note Function 3256 Symbols::. 3257‘defun-close’ 3258 Brace that closes a top-level function definition. *note Function 3259 Symbols::. 3260‘defun-block-intro’ 3261 The first line in a top-level defun. *note Function Symbols::. 3262‘class-open’ 3263 Brace that opens a class definition. *note Class Symbols::. 3264‘class-close’ 3265 Brace that closes a class definition. *note Class Symbols::. 3266‘inline-open’ 3267 Brace that opens an in-class inline method. *note Class Symbols::. 3268‘inline-close’ 3269 Brace that closes an in-class inline method. *note Class 3270 Symbols::. 3271‘func-decl-cont’ 3272 The region between a function definition’s argument list and the 3273 function opening brace (excluding K&R argument declarations). In 3274 C, you cannot put anything but whitespace and comments in this 3275 region, however in C++ and Java, ‘throws’ declarations and other 3276 things can appear here. *note Literal Symbols::. 3277‘knr-argdecl-intro’ 3278 First line of a K&R C argument declaration. *note K&R Symbols::. 3279‘knr-argdecl’ 3280 Subsequent lines in a K&R C argument declaration. *note K&R 3281 Symbols::. 3282‘topmost-intro’ 3283 The first line in a “topmost” definition. *note Function 3284 Symbols::. 3285‘topmost-intro-cont’ 3286 Topmost definition continuation lines. This is only used in the 3287 parts that aren’t covered by other symbols such as ‘func-decl-cont’ 3288 and ‘knr-argdecl’. *note Function Symbols::. 3289‘annotation-top-cont’ 3290 Topmost definition continuation lines where all previous items are 3291 annotations. *note Java Symbols::. 3292‘member-init-intro’ 3293 First line in a member initialization list. *note Class Symbols::. 3294‘member-init-cont’ 3295 Subsequent member initialization list lines. *note Class 3296 Symbols::. 3297‘inher-intro’ 3298 First line of a multiple inheritance list. *note Class Symbols::. 3299‘inher-cont’ 3300 Subsequent multiple inheritance lines. *note Class Symbols::. 3301‘block-open’ 3302 Statement block open brace. *note Literal Symbols::. 3303‘block-close’ 3304 Statement block close brace. *note Conditional Construct 3305 Symbols::. 3306‘brace-list-open’ 3307 Open brace of an enum or static array list. *note Brace List 3308 Symbols::. 3309‘brace-list-close’ 3310 Close brace of an enum or static array list. *note Brace List 3311 Symbols::. 3312‘brace-list-intro’ 3313 First line after the opening ‘{’ in an enum or static array list. 3314 *note Brace List Symbols::. 3315‘brace-list-entry’ 3316 Subsequent lines in an enum or static array list. *note Brace List 3317 Symbols::. 3318‘brace-entry-open’ 3319 Subsequent lines in an enum or static array list where the line 3320 begins with an open brace. *note Brace List Symbols::. 3321‘statement’ 3322 A statement. *note Function Symbols::. 3323‘statement-cont’ 3324 A continuation of a statement. *note Function Symbols::. 3325‘annotation-var-cont’ 3326 A continuation of a statement where all previous items are 3327 annotations. *note Java Symbols::. 3328‘statement-block-intro’ 3329 The first line in a new statement block. *note Conditional 3330 Construct Symbols::. 3331‘statement-case-intro’ 3332 The first line in a case block. *note Switch Statement Symbols::. 3333‘statement-case-open’ 3334 The first line in a case block that starts with a brace. *note 3335 Switch Statement Symbols::. 3336‘substatement’ 3337 The first line after a conditional or loop construct. *note 3338 Conditional Construct Symbols::. 3339‘substatement-open’ 3340 The brace that opens a substatement block. *note Conditional 3341 Construct Symbols::. 3342‘substatement-label’ 3343 The first line after a conditional or loop construct if it’s a 3344 label. *note Conditional Construct Symbols::. 3345‘case-label’ 3346 A label in a ‘switch’ block. *note Switch Statement Symbols::. 3347‘access-label’ 3348 C++ access control label. *note Class Symbols::. 3349‘label’ 3350 Any other label. *note Literal Symbols::. 3351‘do-while-closure’ 3352 The ‘while’ line that ends a ‘do’-‘while’ construct. *note 3353 Conditional Construct Symbols::. 3354‘else-clause’ 3355 The ‘else’ line of an ‘if’-‘else’ construct. *note Conditional 3356 Construct Symbols::. 3357‘catch-clause’ 3358 The ‘catch’ or ‘finally’ (in Java) line of a ‘try’-‘catch’ 3359 construct. *note Conditional Construct Symbols::. 3360‘comment-intro’ 3361 A line containing only a comment introduction. *note Literal 3362 Symbols::. 3363‘arglist-intro’ 3364 The first line in an argument list. *note Paren List Symbols::. 3365‘arglist-cont’ 3366 Subsequent argument list lines when no arguments follow on the same 3367 line as the arglist opening paren. *note Paren List Symbols::. 3368‘arglist-cont-nonempty’ 3369 Subsequent argument list lines when at least one argument follows 3370 on the same line as the arglist opening paren. *note Paren List 3371 Symbols::. 3372‘arglist-close’ 3373 The solo close paren of an argument list. *note Paren List 3374 Symbols::. 3375‘stream-op’ 3376 Lines continuing a stream operator (C++ only). *note Literal 3377 Symbols::. 3378‘inclass’ 3379 The line is nested inside a class definition. *note Class 3380 Symbols::. 3381‘cpp-macro’ 3382 The start of a preprocessor macro definition. *note Literal 3383 Symbols::. 3384‘cpp-define-intro’ 3385 The first line inside a multiline preprocessor macro if 3386 ‘c-syntactic-indentation-in-macros’ is set. *note Multiline Macro 3387 Symbols::. 3388‘cpp-macro-cont’ 3389 All lines inside multiline preprocessor macros if 3390 ‘c-syntactic-indentation-in-macros’ is ‘nil’. *note Multiline 3391 Macro Symbols::. 3392‘friend’ 3393 A C++ friend declaration. *note Class Symbols::. 3394‘objc-method-intro’ 3395 The first line of an Objective-C method definition. *note 3396 Objective-C Method Symbols::. 3397‘objc-method-args-cont’ 3398 Lines continuing an Objective-C method definition. *note 3399 Objective-C Method Symbols::. 3400‘objc-method-call-cont’ 3401 Lines continuing an Objective-C method call. *note Objective-C 3402 Method Symbols::. 3403‘extern-lang-open’ 3404 Brace that opens an ‘extern’ block (e.g., ‘extern "C" {...}’). 3405 *note External Scope Symbols::. 3406‘extern-lang-close’ 3407 Brace that closes an ‘extern’ block. *note External Scope 3408 Symbols::. 3409‘inextern-lang’ 3410 Analogous to ‘inclass’ syntactic symbol, but used inside ‘extern’ 3411 blocks. *note External Scope Symbols::. 3412‘namespace-open’ 3413‘namespace-close’ 3414‘innamespace’ 3415 These are analogous to the three ‘extern-lang’ symbols above, but 3416 are returned for C++ namespace blocks. *note External Scope 3417 Symbols::. 3418‘module-open’ 3419‘module-close’ 3420‘inmodule’ 3421 Analogous to the above, but for CORBA IDL ‘module’ blocks. *note 3422 External Scope Symbols::. 3423‘composition-open’ 3424‘composition-close’ 3425‘incomposition’ 3426 Analogous to the above, but for CORBA CIDL ‘composition’ blocks. 3427 *note External Scope Symbols::. 3428‘template-args-cont’ 3429 C++ template argument list continuations. *note Class Symbols::. 3430‘inlambda’ 3431 Analogous to ‘inclass’ syntactic symbol, but used inside lambda 3432 (i.e., anonymous) functions. Used in C++ and Pike modes. *note 3433 Statement Block Symbols::. 3434‘lambda-intro-cont’ 3435 Lines continuing the header of a lambda function, i.e., between the 3436 ‘lambda’ keyword and the function body. Only used in Pike mode. 3437 *note Statement Block Symbols::. 3438‘inexpr-statement’ 3439 A statement block inside an expression. The gcc C and C++ 3440 extension for this is recognized. It’s also used for the special 3441 functions that take a statement block as an argument in Pike. 3442 *note Statement Block Symbols::. 3443‘inexpr-class’ 3444 A class definition inside an expression. This is used for 3445 anonymous classes in Java. It’s also used for anonymous array 3446 initializers in Java. *note Java Symbols::. 3447 3448* Menu: 3449 3450* Function Symbols:: 3451* Class Symbols:: 3452* Conditional Construct Symbols:: 3453* Switch Statement Symbols:: 3454* Brace List Symbols:: 3455* External Scope Symbols:: 3456* Paren List Symbols:: 3457* Literal Symbols:: 3458* Multiline Macro Symbols:: 3459* Objective-C Method Symbols:: 3460* Java Symbols:: 3461* Statement Block Symbols:: 3462* K&R Symbols:: 3463 3464 3465File: ccmode.info, Node: Function Symbols, Next: Class Symbols, Prev: Syntactic Symbols, Up: Syntactic Symbols 3466 346710.2.1 Function Symbols 3468----------------------- 3469 3470This example shows a typical function declaration. 3471 3472 1: void 3473 2: swap( int& a, int& b ) 3474 3: { 3475 4: int tmp = a; 3476 5: a = b; 3477 6: b = tmp; 3478 7: int ignored = 3479 8: a + b; 3480 9: } 3481 3482 Line 1 shows a ‘topmost-intro’ since it is the first line that 3483introduces a top-level construct. Line 2 is a continuation of the 3484top-level construct introduction so it has the syntax 3485‘topmost-intro-cont’. Line 3 shows a ‘defun-open’ since it is the brace 3486that opens a top-level function definition. Line 9 is the corresponding 3487‘defun-close’ since it contains the brace that closes the top-level 3488function definition. Line 4 is a ‘defun-block-intro’, i.e., it is the 3489first line of a brace-block, enclosed in a top-level function 3490definition. 3491 3492 Lines 5, 6, and 7 are all given ‘statement’ syntax since there isn’t 3493much special about them. Note however that line 8 is given 3494‘statement-cont’ syntax since it continues the statement begun on the 3495previous line. 3496 3497 3498File: ccmode.info, Node: Class Symbols, Next: Conditional Construct Symbols, Prev: Function Symbols, Up: Syntactic Symbols 3499 350010.2.2 Class related Symbols 3501---------------------------- 3502 3503Here’s an example which illustrates some C++ class syntactic symbols: 3504 3505 1: class Bass 3506 2: : public Guitar, 3507 3: public Amplifiable 3508 4: { 3509 5: public: 3510 6: Bass() 3511 7: : eString( new BassString( 0.105 )), 3512 8: aString( new BassString( 0.085 )), 3513 9: dString( new BassString( 0.065 )), 3514 10: gString( new BassString( 0.045 )) 3515 11: { 3516 12: eString.tune( 'E' ); 3517 13: aString.tune( 'A' ); 3518 14: dString.tune( 'D' ); 3519 15: gString.tune( 'G' ); 3520 16: } 3521 17: friend class Luthier; 3522 18: }; 3523 3524 As in the previous example, line 1 has the ‘topmost-intro’ syntax. 3525Here however, the brace that opens a C++ class definition on line 4 is 3526assigned the ‘class-open’ syntax. Note that in C++, classes, structs, 3527and unions are essentially equivalent syntactically (and are very 3528similar semantically), so replacing the ‘class’ keyword in the example 3529above with ‘struct’ or ‘union’ would still result in a syntax of 3530‘class-open’ for line 4 (1). Similarly, line 18 is assigned 3531‘class-close’ syntax. 3532 3533 Line 2 introduces the inheritance list for the class so it is 3534assigned the ‘inher-intro’ syntax, and line 3, which continues the 3535inheritance list is given ‘inher-cont’ syntax. 3536 3537 Hitting ‘C-c C-s’ on line 5 shows the following analysis: 3538 3539 ((inclass 58) (access-label 58)) 3540 3541The primary syntactic symbol for this line is ‘access-label’ as this is 3542a label keyword that specifies access protection in C++. However, 3543because this line is also a top-level construct inside a class 3544definition, the analysis actually shows two syntactic symbols. The 3545other syntactic symbol assigned to this line is ‘inclass’. Similarly, 3546line 6 is given both ‘inclass’ and ‘topmost-intro’ syntax: 3547 3548 ((inclass 58) (topmost-intro 60)) 3549 3550 Line 7 introduces a C++ member initialization list and as such is 3551given ‘member-init-intro’ syntax. Note that in this case it is _not_ 3552assigned ‘inclass’ since this is not considered a top-level construct. 3553Lines 8 through 10 are all assigned ‘member-init-cont’ since they 3554continue the member initialization list started on line 7. 3555 3556 Line 11’s analysis is a bit more complicated: 3557 3558 ((inclass 58) (inline-open)) 3559 3560 This line is assigned a syntax of both ‘inline-open’ and ‘inclass’ 3561because it opens an “in-class” C++ inline method definition. This is 3562distinct from, but related to, the C++ notion of an inline function in 3563that its definition occurs inside an enclosing class definition, which 3564in C++ implies that the function should be inlined. However, if the 3565definition of the ‘Bass’ constructor appeared outside the class 3566definition, the construct would be given the ‘defun-open’ syntax, even 3567if the keyword ‘inline’ appeared before the method name, as in: 3568 3569 1: class Bass 3570 2: : public Guitar, 3571 3: public Amplifiable 3572 4: { 3573 5: public: 3574 6: Bass(); 3575 7: }; 3576 8: 3577 9: inline 3578 10: Bass::Bass() 3579 11: : eString( new BassString( 0.105 )), 3580 12: aString( new BassString( 0.085 )), 3581 13: dString( new BassString( 0.065 )), 3582 14: gString( new BassString( 0.045 )) 3583 15: { 3584 16: eString.tune( 'E' ); 3585 17: aString.tune( 'A' ); 3586 18: dString.tune( 'D' ); 3587 19: gString.tune( 'G' ); 3588 20: } 3589 3590 Returning to the previous example, line 16 is given ‘inline-close’ 3591syntax, while line 12 is given ‘defun-block-open’ syntax, and lines 13 3592through 15 are all given ‘statement’ syntax. Line 17 is interesting in 3593that its syntactic analysis list contains three elements: 3594 3595 ((inclass 58) (topmost-intro 380) (friend)) 3596 3597 The ‘friend’ and ‘inline-open’ syntactic symbols are modifiers that 3598do not have anchor positions. 3599 3600 Template definitions introduce yet another syntactic symbol: 3601 3602 1: ThingManager <int, 3603 2: Framework::Callback *, 3604 3: Mutex> framework_callbacks; 3605 3606 Here, line 1 is analyzed as a ‘topmost-intro’, but lines 2 and 3 are 3607both analyzed as ‘template-args-cont’ lines. 3608 3609 ---------- Footnotes ---------- 3610 3611 (1) This is the case even for C and Objective-C. For consistency, 3612structs in all supported languages are syntactically equivalent to 3613classes. Note however that the keyword ‘class’ is meaningless in C and 3614Objective-C. 3615 3616 3617File: ccmode.info, Node: Conditional Construct Symbols, Next: Switch Statement Symbols, Prev: Class Symbols, Up: Syntactic Symbols 3618 361910.2.3 Conditional Construct Symbols 3620------------------------------------ 3621 3622Here is a (totally contrived) example which illustrates how syntax is 3623assigned to various conditional constructs: 3624 3625 1: void spam( int index ) 3626 2: { 3627 3: for( int i=0; i<index; i++ ) 3628 4: { 3629 5: if( i == 10 ) 3630 6: do_something_special(); 3631 7: else 3632 8: silly_label: 3633 9: do_something( i ); 3634 10: } 3635 11: do { 3636 12: another_thing( i-- ); 3637 13: } 3638 14: while( i > 0 ); 3639 15: } 3640 3641 Only the lines that illustrate new syntactic symbols will be 3642discussed. 3643 3644 Line 4 has a brace which opens a conditional’s substatement block. 3645It is thus assigned ‘substatement-open’ syntax, and since line 5 is the 3646first line in the substatement block, it is assigned 3647‘statement-block-intro’ syntax. Line 10 contains the brace that closes 3648the inner substatement block, and is therefore given the syntax 3649‘block-close’(1). Line 13 is treated the same way. 3650 3651 Lines 6 and 9 are also substatements of conditionals, but since they 3652don’t start blocks they are given ‘substatement’ syntax instead of 3653‘substatement-open’. 3654 3655 Line 8 contains a label, which is normally given ‘label’ syntax. 3656This one is however a bit special since it’s between a conditional and 3657its substatement. It’s analyzed as ‘substatement-label’ to let you 3658handle this rather odd case differently from normal labels. 3659 3660 Line 7 start with an ‘else’ that matches the ‘if’ statement on line 36615. It is therefore given the ‘else-clause’ syntax and is anchored on 3662the matching ‘if’. The ‘try’-‘catch’ constructs in C++ and Java are 3663treated this way too, except that ‘catch’ and (in Java) ‘finally’, are 3664marked with ‘catch-clause’. 3665 3666 The ‘while’ construct on line 14 that closes a ‘do’ conditional is 3667given the special syntax ‘do-while-closure’ if it appears on a line by 3668itself. Note that if the ‘while’ appeared on the same line as the 3669preceding close brace, that line would still have ‘block-close’ syntax. 3670 3671 ---------- Footnotes ---------- 3672 3673 (1) ‘block-open’ is used only for “free-standing” blocks, and is 3674somewhat rare (*note Literal Symbols:: for an example.) 3675 3676 3677File: ccmode.info, Node: Switch Statement Symbols, Next: Brace List Symbols, Prev: Conditional Construct Symbols, Up: Syntactic Symbols 3678 367910.2.4 Switch Statement Symbols 3680------------------------------- 3681 3682Switch statements have their own set of syntactic symbols. Here’s an 3683example: 3684 3685 1: void spam( enum Ingredient i ) 3686 2: { 3687 3: switch( i ) { 3688 4: case Ham: 3689 5: be_a_pig(); 3690 6: break; 3691 7: case Salt: 3692 8: drink_some_water(); 3693 9: break; 3694 10: default: 3695 11: { 3696 12: what_is_it(); 3697 13: break; 3698 14: } 3699 15: } 3700 14: } 3701 3702 Here, lines 4, 7, and 10 are all assigned ‘case-label’ syntax, while 3703lines 5 and 8 are assigned ‘statement-case-intro’. Line 11 is treated 3704slightly differently since it contains a brace that opens a block; it is 3705given ‘statement-case-open’ syntax. 3706 3707 3708File: ccmode.info, Node: Brace List Symbols, Next: External Scope Symbols, Prev: Switch Statement Symbols, Up: Syntactic Symbols 3709 371010.2.5 Brace List Symbols 3711------------------------- 3712 3713There are a set of syntactic symbols that are used to recognize 3714constructs inside of brace lists. A brace list is defined as an ‘enum’ 3715or aggregate initializer list, such as might statically initialize an 3716array of structs. The three special aggregate constructs in Pike, ‘({ 3717})’, ‘([ ])’ and ‘(< >)’, are treated as brace lists too. An example: 3718 3719 1: static char* ingredients[] = 3720 2: { 3721 3: "Ham", 3722 4: "Salt", 3723 5: NULL 3724 6: }; 3725 3726 Following convention, line 2 in this example is assigned 3727‘brace-list-open’ syntax, and line 3 is assigned ‘brace-list-intro’ 3728syntax. Likewise, line 6 is assigned ‘brace-list-close’ syntax. Lines 37294 and 5 however, are assigned ‘brace-list-entry’ syntax, as would all 3730subsequent lines in this initializer list. 3731 3732 Your static initializer might be initializing nested structures, for 3733example: 3734 3735 1: struct intpairs[] = 3736 2: { 3737 3: { 1, 2 }, 3738 4: { 3739 5: 3, 3740 6: 4 3741 7: } 3742 8: { 1, 3743 9: 2 }, 3744 10: { 3, 4 } 3745 11: }; 3746 3747 Here, you’ve already seen the analysis of lines 1, 2, 3, and 11. On 3748line 4, things get interesting; this line is assigned ‘brace-entry-open’ 3749syntactic symbol because it’s a bracelist entry line that starts with an 3750open brace. Lines 5 and 6 are pretty standard, and line 7 is a 3751‘brace-list-close’ as you’d expect. Once again, line 8 is assigned as 3752‘brace-entry-open’ as is line 10. Line 9 is assigned two syntactic 3753elements, ‘brace-list-intro’ with anchor point at the ‘{’ of line 8(1), 3754and ‘brace-list-entry’ anchored on the ‘1’ of line 8. 3755 3756 ---------- Footnotes ---------- 3757 3758 (1) This extra syntactic element was introduced in CC Mode 5.33.1 to 3759allow extra flexibility in indenting the second line of such a 3760construct. You can preserve the behavior resulting from the former 3761syntactic analysis by giving ‘brace-list-entry’ an offset of 3762‘c-lineup-under-anchor’ (*note Misc Line-Up::). 3763 3764 3765File: ccmode.info, Node: External Scope Symbols, Next: Paren List Symbols, Prev: Brace List Symbols, Up: Syntactic Symbols 3766 376710.2.6 External Scope Symbols 3768----------------------------- 3769 3770External language definition blocks also have their own syntactic 3771symbols. In this example: 3772 3773 1: extern "C" 3774 2: { 3775 3: int thing_one( int ); 3776 4: int thing_two( double ); 3777 5: } 3778 3779line 2 is given the ‘extern-lang-open’ syntax, while line 5 is given the 3780‘extern-lang-close’ syntax. The analysis for line 3 yields: 3781 3782 ((inextern-lang) (topmost-intro 14)) 3783 3784where ‘inextern-lang’ is a modifier similar in purpose to ‘inclass’. 3785 3786 There are various other top level blocks like ‘extern’, and they are 3787all treated in the same way except that the symbols are named after the 3788keyword that introduces the block. E.g., C++ namespace blocks get the 3789three symbols ‘namespace-open’, ‘namespace-close’ and ‘innamespace’. 3790The currently recognized top level blocks are: 3791 3792‘extern-lang-open’, ‘extern-lang-close’, ‘inextern-lang’ 3793 ‘extern’ blocks in C and C++.(1) 3794 3795‘namespace-open’, ‘namespace-close’, ‘innamespace’ 3796 ‘namespace’ blocks in C++. 3797 3798‘module-open’, ‘module-close’, ‘inmodule’ 3799 ‘module’ blocks in CORBA IDL. 3800 3801‘composition-open’, ‘composition-close’, ‘incomposition’ 3802 ‘composition’ blocks in CORBA CIDL. 3803 3804 ---------- Footnotes ---------- 3805 3806 (1) These should logically be named ‘extern-open’, ‘extern-close’ and 3807‘inextern’, but that isn’t the case for historical reasons. 3808 3809 3810File: ccmode.info, Node: Paren List Symbols, Next: Literal Symbols, Prev: External Scope Symbols, Up: Syntactic Symbols 3811 381210.2.7 Parenthesis (Argument) List Symbols 3813------------------------------------------ 3814 3815A number of syntactic symbols are associated with parenthesis lists, 3816a.k.a argument lists, as found in function declarations and function 3817calls. This example illustrates these: 3818 3819 1: void a_function( int line1, 3820 2: int line2 ); 3821 3: 3822 4: void a_longer_function( 3823 5: int line1, 3824 6: int line2 3825 7: ); 3826 8: 3827 9: void call_them( int line1, int line2 ) 3828 10: { 3829 11: a_function( 3830 12: line1, 3831 13: line2 3832 14: ); 3833 15: 3834 16: a_longer_function( line1, 3835 17: line2 ); 3836 18: } 3837 3838 Lines 5 and 12 are assigned ‘arglist-intro’ syntax since they are the 3839first line following the open parenthesis, and lines 7 and 14 are 3840assigned ‘arglist-close’ syntax since they contain the parenthesis that 3841closes the argument list. 3842 3843 Lines that continue argument lists can be assigned one of two 3844syntactic symbols. For example, Lines 2 and 17 are assigned 3845‘arglist-cont-nonempty’ syntax. What this means is that they continue 3846an argument list, but that the line containing the parenthesis that 3847opens the list is _not empty_ following the open parenthesis. Contrast 3848this against lines 6 and 13 which are assigned ‘arglist-cont’ syntax. 3849This is because the parenthesis that opens their argument lists is the 3850last character on that line. 3851 3852 Syntactic elements with ‘arglist-intro’, ‘arglist-cont-nonempty’, and 3853‘arglist-close’ contain two buffer positions: the anchor position (the 3854beginning of the declaration or statement) and the position of the open 3855parenthesis. The latter position can be used in a line-up function 3856(*note Line-Up Functions::). 3857 3858 Note that there is no ‘arglist-open’ syntax. This is because any 3859parenthesis that opens an argument list, appearing on a separate line, 3860is assigned the ‘statement-cont’ syntax instead. 3861 3862 3863File: ccmode.info, Node: Literal Symbols, Next: Multiline Macro Symbols, Prev: Paren List Symbols, Up: Syntactic Symbols 3864 386510.2.8 Comment String Label and Macro Symbols 3866--------------------------------------------- 3867 3868A few miscellaneous syntactic symbols that haven’t been previously 3869covered are illustrated by this C++ example: 3870 3871 1: void Bass::play( int volume ) 3872 2: const 3873 3: { 3874 4: /* this line starts a multiline 3875 5: * comment. This line should get 'c' syntax */ 3876 6: 3877 7: char* a_multiline_string = "This line starts a multiline \ 3878 8: string. This line should get 'string' syntax."; 3879 9: 3880 10: note: 3881 11: { 3882 12: #ifdef LOCK 3883 13: Lock acquire(); 3884 14: #endif // LOCK 3885 15: slap_pop(); 3886 16: cout << "I played " 3887 17: << "a note\n"; 3888 18: } 3889 19: } 3890 3891 The lines to note in this example include: 3892 3893 • Line 2 is assigned the ‘func-decl-cont’ syntax. 3894 3895 • Line 4 is assigned both ‘defun-block-intro’ _and_ ‘comment-intro’ 3896 syntax. A syntactic element with ‘comment-intro’ has no anchor 3897 point. It is always accompanied by another syntactic element which 3898 does have one. 3899 3900 • Line 5 is assigned ‘c’ syntax. 3901 3902 • Line 6 which, even though it contains nothing but whitespace, is 3903 assigned ‘defun-block-intro’. Note that the appearance of the 3904 comment on lines 4 and 5 do not cause line 6 to be assigned 3905 ‘statement’ syntax because comments are considered to be “syntactic 3906 whitespace”, which are ignored when analyzing code. 3907 3908 • Line 8 is assigned ‘string’ syntax. 3909 3910 • Line 10 is assigned ‘label’ syntax. 3911 3912 • Line 11 is assigned ‘block-open’ as well as ‘statement’ syntax. A 3913 ‘block-open’ syntactic element doesn’t have an anchor position, 3914 since it always appears with another syntactic element which does 3915 have one. 3916 3917 • Lines 12 and 14 are assigned ‘cpp-macro’ syntax in addition to the 3918 normal syntactic symbols (‘statement-block-intro’ and ‘statement’, 3919 respectively). Normally ‘cpp-macro’ is configured to cancel out 3920 the normal syntactic context to make all preprocessor directives 3921 stick to the first column, but that’s easily changed if you want 3922 preprocessor directives to be indented like the rest of the code. 3923 Like ‘comment-intro’, a syntactic element with ‘cpp-macro’ doesn’t 3924 contain an anchor position. 3925 3926 • Line 17 is assigned ‘stream-op’ syntax. 3927 3928 3929File: ccmode.info, Node: Multiline Macro Symbols, Next: Objective-C Method Symbols, Prev: Literal Symbols, Up: Syntactic Symbols 3930 393110.2.9 Multiline Macro Symbols 3932------------------------------ 3933 3934Multiline preprocessor macro definitions are normally handled just like 3935other code, i.e., the lines inside them are indented according to the 3936syntactic analysis of the preceding lines inside the macro. The first 3937line inside a macro definition (i.e., the line after the starting line 3938of the cpp directive itself) gets ‘cpp-define-intro’. In this example: 3939 3940 1: #define LIST_LOOP(cons, listp) \ 3941 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ 3942 3: if (!CONSP (cons)) \ 3943 4: signal_error ("Invalid list format", listp); \ 3944 5: else 3945 3946line 1 is given the syntactic symbol ‘cpp-macro’. The first line of a 3947cpp directive is always given that symbol. Line 2 is given 3948‘cpp-define-intro’, so that you can give the macro body as a whole some 3949extra indentation. Lines 3 through 5 are then analyzed as normal code, 3950i.e., ‘substatement’ on lines 3 and 4, and ‘else-clause’ on line 5. 3951 3952 The syntactic analysis inside macros can be turned off with 3953‘c-syntactic-indentation-in-macros’ (*note Custom Macros::). In that 3954case, lines 2 through 5 would all be given ‘cpp-macro-cont’ with an 3955anchor position pointing to the ‘#’ which starts the cpp directive(1). 3956 3957 *Note Custom Macros::, for more info about the treatment of macros. 3958 3959 ---------- Footnotes ---------- 3960 3961 (1) This is how CC Mode 5.28 and earlier analyzed macros. 3962 3963 3964File: ccmode.info, Node: Objective-C Method Symbols, Next: Java Symbols, Prev: Multiline Macro Symbols, Up: Syntactic Symbols 3965 396610.2.10 Objective-C Method Symbols 3967---------------------------------- 3968 3969In Objective-C buffers, there are three additional syntactic symbols 3970assigned to various message calling constructs. Here’s an example 3971illustrating these: 3972 3973 1: - (void)setDelegate:anObject 3974 2: withStuff:stuff 3975 3: { 3976 4: [delegate masterWillRebind:self 3977 5: toDelegate:anObject 3978 6: withExtraStuff:stuff]; 3979 7: } 3980 3981 Here, line 1 is assigned ‘objc-method-intro’ syntax, and line 2 is 3982assigned ‘objc-method-args-cont’ syntax. Lines 5 and 6 are both 3983assigned ‘objc-method-call-cont’ syntax. 3984 3985 3986File: ccmode.info, Node: Java Symbols, Next: Statement Block Symbols, Prev: Objective-C Method Symbols, Up: Syntactic Symbols 3987 398810.2.11 Java Symbols 3989-------------------- 3990 3991Java has a concept of anonymous classes which can look something like 3992this: 3993 3994 1: @Test 3995 2: public void watch(Observable o) { 3996 3: @NonNull 3997 4: Observer obs = new Observer() { 3998 5: public void update(Observable o, Object arg) { 3999 6: history.addElement(arg); 4000 7: } 4001 8: }; 4002 9: o.addObserver(obs); 4003 10: } 4004 4005 The brace following the ‘new’ operator opens the anonymous class. 4006Lines 5 and 8 are assigned the ‘inexpr-class’ syntax, besides the 4007‘inclass’ symbol used in normal classes. Thus, the class will be 4008indented just like a normal class, with the added indentation given to 4009‘inexpr-class’. An ‘inexpr-class’ syntactic element doesn’t have an 4010anchor position. 4011 4012 Line 2 is assigned the ‘annotation-top-cont’ syntax, due to it being 4013a continuation of a topmost introduction with an annotation symbol 4014preceding the current line. Similarly, line 4 is assigned the 4015‘annotation-var-cont’ syntax due to it being a continuation of a 4016variable declaration where preceding the declaration is an annotation. 4017 4018 4019File: ccmode.info, Node: Statement Block Symbols, Next: K&R Symbols, Prev: Java Symbols, Up: Syntactic Symbols 4020 402110.2.12 Statement Block Symbols 4022------------------------------- 4023 4024There are a few occasions where a statement block might be used inside 4025an expression. One is in C or C++ code using the gcc extension for 4026this, e.g.: 4027 4028 1: int res = ({ 4029 2: int y = foo (); int z; 4030 3: if (y > 0) z = y; else z = - y; 4031 4: z; 4032 5: }); 4033 4034 Lines 2 and 5 get the ‘inexpr-statement’ syntax, besides the symbols 4035they’d get in a normal block. Therefore, the indentation put on 4036‘inexpr-statement’ is added to the normal statement block indentation. 4037An ‘inexpr-statement’ syntactic element doesn’t contain an anchor 4038position. 4039 4040 C++11’s lambda expressions involve a block inside a statement. For 4041example: 4042 4043 1: std::for_each(someList.begin(), someList.end(), [&total](int x) { 4044 2: total += x; 4045 3: }); 4046 4047 Here a lambda expressions begins at the open bracket on line 1 and 4048ends at the closing brace on line 3. Line 2, in addition to the 4049familiar ‘defun-block-intro’ syntactic element, is also prefixed by an 4050‘inlambda’ element, which is typically used to indent the entire lambda 4051expression to under the opening bracket. 4052 4053 In Pike code, there are a few other situations where blocks occur 4054inside statements, as illustrated here: 4055 4056 1: array itgob() 4057 2: { 4058 3: string s = map (backtrace()[-2][3..], 4059 4: lambda 4060 5: (mixed arg) 4061 6: { 4062 7: return sprintf ("%t", arg); 4063 8: }) * ", " + "\n"; 4064 9: return catch { 4065 10: write (s + "\n"); 4066 11: }; 4067 12: } 4068 4069 Lines 4 through 8 contain a lambda function, which CC Mode recognizes 4070by the ‘lambda’ keyword. If the function argument list is put on a line 4071of its own, as in line 5, it gets the ‘lambda-intro-cont’ syntax. The 4072function body is handled as an inline method body, with the addition of 4073the ‘inlambda’ syntactic symbol. This means that line 6 gets ‘inlambda’ 4074and ‘inline-open’, and line 8 gets ‘inline-close’(1). 4075 4076 On line 9, ‘catch’ is a special function taking a statement block as 4077its argument. The block is handled as an in-expression statement with 4078the ‘inexpr-statement’ syntax, just like the gcc extended C example 4079above. The other similar special function, ‘gauge’, is handled like 4080this too. 4081 4082 ---------- Footnotes ---------- 4083 4084 (1) You might wonder why it doesn’t get ‘inlambda’ too. It’s because 4085the closing brace is relative to the opening brace, which stands on its 4086own line in this example. If the opening brace was hanging on the 4087previous line, then the closing brace would get the ‘inlambda’ syntax 4088too to be indented correctly. 4089 4090 4091File: ccmode.info, Node: K&R Symbols, Prev: Statement Block Symbols, Up: Syntactic Symbols 4092 409310.2.13 K&R Symbols 4094------------------- 4095 4096Two other syntactic symbols can appear in old style, non-prototyped C 4097code (1): 4098 4099 1: int add_three_integers(a, b, c) 4100 2: int a; 4101 3: int b; 4102 4: int c; 4103 5: { 4104 6: return a + b + c; 4105 7: } 4106 4107 Here, line 2 is the first line in an argument declaration list and so 4108is given the ‘knr-argdecl-intro’ syntactic symbol. Subsequent lines 4109(i.e., lines 3 and 4 in this example), are given ‘knr-argdecl’ syntax. 4110 4111 ---------- Footnotes ---------- 4112 4113 (1) a.k.a. K&R C, or Kernighan & Ritchie C 4114 4115 4116File: ccmode.info, Node: Indentation Calculation, Prev: Syntactic Symbols, Up: Indentation Engine Basics 4117 411810.3 Indentation Calculation 4119============================ 4120 4121Indentation for a line is calculated from the syntactic context (*note 4122Syntactic Analysis::). 4123 4124 First, a buffer position is found whose column will be the base for 4125the indentation calculation. It’s the anchor position in the first 4126syntactic element that provides one that is used. If no syntactic 4127element has an anchor position then column zero is used. 4128 4129 Second, the syntactic symbols in each syntactic element are looked up 4130in the ‘c-offsets-alist’ style variable (*note c-offsets-alist::), which 4131is an association list of syntactic symbols and the offsets to apply for 4132those symbols. These offsets are added together with the base column to 4133produce the new indentation column. 4134 4135 Let’s use our two code examples above to see how this works. Here is 4136our first example again: 4137 4138 1: void swap( int& a, int& b ) 4139 2: { 4140 3: int tmp = a; 4141 4: a = b; 4142 5: b = tmp; 4143 6: } 4144 4145 Let’s say point is on line 3 and we hit the <TAB> key to reindent the 4146line. The syntactic context for that line is: 4147 4148 ((defun-block-intro 29)) 4149 4150Since buffer position 29 is the first and only anchor position in the 4151list, CC Mode goes there and asks for the current column. This brace is 4152in column zero, so CC Mode uses ‘0’ as the base column. 4153 4154 Next, CC Mode looks up ‘defun-block-intro’ in the ‘c-offsets-alist’ 4155style variable. Let’s say it finds the value ‘4’; it adds this to the 4156base column ‘0’, yielding a running total indentation of 4 spaces. 4157 4158 Since there is only one syntactic element on the list for this line, 4159indentation calculation is complete, and the total indentation for the 4160line is 4 spaces. 4161 4162 Here’s another example: 4163 4164 1: int add( int val, int incr, int doit ) 4165 2: { 4166 3: if( doit ) 4167 4: { 4168 5: return( val + incr ); 4169 6: } 4170 7: return( val ); 4171 8: } 4172 4173 If we were to hit ‘TAB’ on line 4 in the above example, the same 4174basic process is performed, despite the differences in the syntactic 4175context. The context for this line is: 4176 4177 ((substatement-open 46)) 4178 4179 Here, CC Mode goes to buffer position 46, which is the ‘i’ in ‘if’ on 4180line 3. This character is in the fourth column on that line so the base 4181column is ‘4’. Then CC Mode looks up the ‘substatement-open’ symbol in 4182‘c-offsets-alist’. Let’s say it finds the value ‘4’. It’s added with 4183the base column and yields an indentation for the line of 8 spaces. 4184 4185 Simple, huh? 4186 4187 Actually, it’s a bit more complicated than that since the entries on 4188‘c-offsets-alist’ can be much more than plain offsets. *Note 4189c-offsets-alist::, for the full story. 4190 4191 Anyway, the mode usually just does The Right Thing without you having 4192to think about it in this much detail. But when customizing 4193indentation, it’s helpful to understand the general indentation model 4194being used. 4195 4196 As you configure CC Mode, you might want to set the variable 4197‘c-echo-syntactic-information-p’ to non-‘nil’ so that the syntactic 4198context and calculated offset always is echoed in the minibuffer when 4199you hit ‘TAB’. 4200 4201 4202File: ccmode.info, Node: Customizing Indentation, Next: Custom Macros, Prev: Indentation Engine Basics, Up: Top 4203 420411 Customizing Indentation 4205************************** 4206 4207The principal variable for customizing indentation is the style variable 4208‘c-offsets-alist’, which gives an “offset” (an indentation rule) for 4209each syntactic symbol. Its structure and semantics are completely 4210described in *note c-offsets-alist::. The various ways you can set the 4211variable, including the use of the CC Mode style system, are described 4212in *note Config Basics:: and its sections, in particular *note Style 4213Variables::. 4214 4215 The simplest and most used kind of “offset” setting in 4216‘c-offsets-alist’ is in terms of multiples of ‘c-basic-offset’: 4217 4218 -- User Option: c-basic-offset 4219 This style variable holds the basic offset between indentation 4220 levels. Its factory default is 4, but all the built-in styles set 4221 it themselves, to some value between 2 (for ‘gnu’ style) and 8 (for 4222 ‘bsd’, ‘linux’, and ‘python’ styles). 4223 4224 The most flexible “offset” setting you can make in ‘c-offsets-alist’ 4225is a line-up function (or even a list of them), either one supplied by 4226CC Mode (*note Line-Up Functions::) or one you write yourself (*note 4227Custom Line-Up::). 4228 4229 Finally, in *note Other Indentation:: you’ll find the tool of last 4230resort: a hook which is called after a line has been indented. You can 4231install functions here to make ad-hoc adjustments to any line’s 4232indentation. 4233 4234* Menu: 4235 4236* c-offsets-alist:: 4237* Interactive Customization:: 4238* Line-Up Functions:: 4239* Custom Line-Up:: 4240* Other Indentation:: 4241 4242 4243File: ccmode.info, Node: c-offsets-alist, Next: Interactive Customization, Prev: Customizing Indentation, Up: Customizing Indentation 4244 424511.1 c-offsets-alist 4246==================== 4247 4248This section explains the structure and semantics of the style variable 4249‘c-offsets-alist’, the principal variable for configuring indentation. 4250Details of how to set it up, and its relationship to CC Mode’s style 4251system are given in *note Style Variables::. 4252 4253 -- User Option: c-offsets-alist 4254 This is an alist which associates an offset with each syntactic 4255 symbol. This “offset” is a rule specifying how to indent a line 4256 whose syntactic context matches the symbol. *Note Syntactic 4257 Analysis::. 4258 4259 Note that the buffer-local binding of this alist in a CC Mode 4260 buffer contains an entry for _every_ syntactic symbol. Its global 4261 binding and its settings within style specifications usually 4262 contain only a few entries. *Note Style Variables::. 4263 4264 The offset specification associated with any particular syntactic 4265 symbol can be an integer, a variable name, a vector, a function or 4266 lambda expression, a list, or one of the following special symbols: 4267 ‘+’, ‘-’, ‘++’, ‘--’, ‘*’, or ‘/’. The meanings of these values 4268 are described in detail below. 4269 4270 Here is an example fragment of a ‘c-offsets-alist’, showing some of 4271 these kinds of offsets: 4272 4273 ((statement . 0) 4274 (substatement . +) 4275 (cpp-macro . [0]) 4276 (topmost-intro-cont . c-lineup-topmost-intro-cont) 4277 (statement-block-intro . (add c-lineup-whitesmith-in-block 4278 c-indent-multi-line-block)) 4279 ... 4280 4281 ) 4282 4283 -- Command: c-set-offset (‘C-c C-o’) 4284 This command changes the entry for a syntactic symbol in the 4285 current binding of ‘c-offsets-alist’, or it inserts a new entry if 4286 there isn’t already one for that syntactic symbol. 4287 4288 You can use ‘c-set-offset’ interactively within a CC Mode buffer to 4289 make experimental changes to your indentation settings. ‘C-c C-o’ 4290 prompts you for the syntactic symbol to change (defaulting to that 4291 of the current line) and the new offset (defaulting to the current 4292 offset). 4293 4294 ‘c-set-offset’ takes two arguments when used programmatically: 4295 SYMBOL, the syntactic element symbol to change and OFFSET, the new 4296 offset for that syntactic element. You can call the command in 4297 your ‘.emacs’ to change the global binding of ‘c-offsets-alist’ 4298 (*note Style Variables::); you can use it in a hook function to 4299 make changes from the current style. CC Mode itself uses this 4300 function when initializing styles. 4301 4302 The “offset specifications” in ‘c-offsets-alist’ can be any of the 4303following: 4304 4305An integer 4306 The integer specifies a relative offset. All relative offsets(1) 4307 will be added together and used to calculate the indentation 4308 relative to an anchor position earlier in the buffer. *Note 4309 Indentation Calculation::, for details. Most of the time, it’s 4310 probably better to use one of the special symbols like ‘+’ than an 4311 integer (apart from zero). 4312 4313One of the symbols ‘+’, ‘-’, ‘++’, ‘--’, ‘*’, or ‘/’ 4314 These special symbols describe a relative offset in multiples of 4315 ‘c-basic-offset’: 4316 4317 By defining a style’s indentation in terms of ‘c-basic-offset’, you 4318 can change the amount of whitespace given to an indentation level 4319 while maintaining the same basic shape of your code. Here are the 4320 values that the special symbols correspond to: 4321 4322 ‘+’ 4323 ‘c-basic-offset’ times 1 4324 ‘-’ 4325 ‘c-basic-offset’ times −1 4326 ‘++’ 4327 ‘c-basic-offset’ times 2 4328 ‘--’ 4329 ‘c-basic-offset’ times −2 4330 ‘*’ 4331 ‘c-basic-offset’ times 0.5 4332 ‘/’ 4333 ‘c-basic-offset’ times −0.5 4334 4335A vector 4336 The first element of the vector, an integer, sets the absolute 4337 indentation column. This will override any previously calculated 4338 indentation, but won’t override relative indentation calculated 4339 from syntactic elements later on in the syntactic context of the 4340 line being indented. *Note Indentation Calculation::. Any 4341 elements in the vector beyond the first will be ignored. 4342 4343A function or lambda expression 4344 The function will be called and its return value will in turn be 4345 evaluated as an offset specification. Functions are useful when 4346 more context than just the syntactic symbol is needed to get the 4347 desired indentation. *Note Line-Up Functions::, and *note Custom 4348 Line-Up::, for details about them. 4349 4350A symbol with a variable binding 4351 If the symbol also has a function binding, the function takes 4352 precedence over the variable. Otherwise the value of the variable 4353 is used. It must be an integer (which is used as relative offset) 4354 or a vector (an absolute offset). 4355 4356A list 4357 The offset can also be a list containing several offset 4358 specifications; these are evaluated recursively and combined. A 4359 list is typically only useful when some of the offsets are line-up 4360 functions. A common strategy is calling a sequence of functions in 4361 turn until one of them recognizes that it is appropriate for the 4362 source line and returns a non-‘nil’ value. 4363 4364 ‘nil’ values are always ignored when the offsets are combined. The 4365 first element of the list specifies the method of combining the 4366 non-‘nil’ offsets from the remaining elements: 4367 4368 ‘first’ 4369 Use the first offset that doesn’t evaluate to ‘nil’. 4370 Subsequent elements of the list don’t get evaluated. 4371 ‘min’ 4372 Use the minimum of all the offsets. All must be either 4373 relative or absolute; they can’t be mixed. 4374 ‘max’ 4375 Use the maximum of all the offsets. All must be either 4376 relative or absolute; they can’t be mixed. 4377 ‘add’ 4378 Add all the evaluated offsets together. Exactly one of them 4379 may be absolute, in which case the result is absolute. Any 4380 relative offsets that preceded the absolute one in the list 4381 will be ignored in that case. 4382 4383 As a compatibility measure, if the first element is none of the 4384 above then it too will be taken as an offset specification and the 4385 whole list will be combined according to the method ‘first’. 4386 4387 If an offset specification evaluates to ‘nil’, then a relative offset 4388of 0 (zero) is used(2). 4389 4390 ---------- Footnotes ---------- 4391 4392 (1) The syntactic context 4393‘((defun-block-intro 2724) (comment-intro))’ would likely have two 4394relative offsets. 4395 4396 (2) There is however a variable ‘c-strict-syntax-p’ that when set to 4397non-‘nil’ will cause an error to be signaled in that case. It’s now 4398considered obsolete since it doesn’t work well with some of the 4399alignment functions that return ‘nil’ instead of zero. You should 4400therefore leave ‘c-strict-syntax-p’ set to ‘nil’. 4401 4402 4403File: ccmode.info, Node: Interactive Customization, Next: Line-Up Functions, Prev: c-offsets-alist, Up: Customizing Indentation 4404 440511.2 Interactive Customization 4406============================== 4407 4408As an example of how to customize indentation, let’s change the style of 4409this example(1): 4410 4411 1: int add( int val, int incr, int doit ) 4412 2: { 4413 3: if( doit ) 4414 4: { 4415 5: return( val + incr ); 4416 6: } 4417 7: return( val ); 4418 8: } 4419 4420to: 4421 4422 1: int add( int val, int incr, int doit ) 4423 2: { 4424 3: if( doit ) 4425 4: { 4426 5: return( val + incr ); 4427 6: } 4428 7: return( val ); 4429 8: } 4430 4431 In other words, we want to change the indentation of braces that open 4432a block following a condition so that the braces line up under the 4433conditional, instead of being indented. Notice that the construct we 4434want to change starts on line 4. To change the indentation of a line, 4435we need to see which syntactic symbols affect the offset calculations 4436for that line. Hitting ‘C-c C-s’ on line 4 yields: 4437 4438 ((substatement-open 44)) 4439 4440so we know that to change the offset of the open brace, we need to 4441change the indentation for the ‘substatement-open’ syntactic symbol. 4442 4443 To do this interactively, just hit ‘C-c C-o’. This prompts you for 4444the syntactic symbol to change, providing a reasonable default. In this 4445case, the default is ‘substatement-open’, which is just the syntactic 4446symbol we want to change! 4447 4448 After you hit return, CC Mode will then prompt you for the new offset 4449value, with the old value as the default. The default in this case is 4450‘+’, but we want no extra indentation so enter ‘0’ and ‘RET’. This will 4451associate the offset 0 with the syntactic symbol ‘substatement-open’. 4452 4453 To check your changes quickly, just hit ‘C-c C-q’ (‘c-indent-defun’) 4454to reindent the entire function. The example should now look like: 4455 4456 1: int add( int val, int incr, int doit ) 4457 2: { 4458 3: if( doit ) 4459 4: { 4460 5: return( val + incr ); 4461 6: } 4462 7: return( val ); 4463 8: } 4464 4465 Notice how just changing the open brace offset on line 4 is all we 4466needed to do. Since the other affected lines are indented relative to 4467line 4, they are automatically indented the way you’d expect. For more 4468complicated examples, this might not always work. The general approach 4469to take is to always start adjusting offsets for lines higher up in the 4470file, then reindent and see if any following lines need further 4471adjustments. 4472 4473 -- Command: c-set-offset symbol offset 4474 This is the command bound to ‘C-c C-o’. It provides a convenient 4475 way to set offsets on ‘c-offsets-alist’ both interactively (see the 4476 example above) and from your mode hook. 4477 4478 It takes two arguments when used programmatically: SYMBOL is the 4479 syntactic element symbol to change and OFFSET is the new offset for 4480 that syntactic element. 4481 4482 ---------- Footnotes ---------- 4483 4484 (1) In this and subsequent examples, the original code is formatted 4485using the ‘gnu’ style unless otherwise indicated. *Note Styles::. 4486 4487 4488File: ccmode.info, Node: Line-Up Functions, Next: Custom Line-Up, Prev: Interactive Customization, Up: Customizing Indentation 4489 449011.3 Line-Up Functions 4491====================== 4492 4493Often there are cases when a simple offset setting on a syntactic symbol 4494isn’t enough to get the desired indentation—for example, you might want 4495to line up a closing parenthesis with the matching opening one rather 4496than indenting relative to its “anchor point”. CC Mode provides this 4497flexibility with “line-up functions”. 4498 4499 The way you associate a line-up function with a syntactic symbol is 4500described in *note c-offsets-alist::. CC Mode comes with many 4501predefined line-up functions for common situations. If none of these 4502does what you want, you can write your own. *Note Custom Line-Up::. 4503Sometimes, it is easier to tweak the standard indentation by adding a 4504function to ‘c-special-indent-hook’ (*note Other Indentation::). 4505 4506 The line-up functions haven’t been adapted for AWK buffers or tested 4507with them. Some of them might work serendipitously. There shouldn’t be 4508any problems writing custom line-up functions for AWK mode. 4509 4510 The calling convention for line-up functions is described fully in 4511*note Custom Line-Up::. Roughly speaking, the return value is either an 4512offset itself (such as ‘+’ or ‘[0]’), another line-up function, or it’s 4513‘nil’, meaning “this function is inappropriate in this case - try a 4514different one”. *Note c-offsets-alist::. 4515 4516 The subsections below describe all the standard line-up functions, 4517categorized by the sort of token the lining-up centers around. For each 4518of these functions there is a “works with” list that indicates which 4519syntactic symbols the function is intended to be used with. 4520 4521* Menu: 4522 4523* Brace/Paren Line-Up:: 4524* List Line-Up:: 4525* Operator Line-Up:: 4526* Comment Line-Up:: 4527* Misc Line-Up:: 4528 4529 4530File: ccmode.info, Node: Brace/Paren Line-Up, Next: List Line-Up, Prev: Line-Up Functions, Up: Line-Up Functions 4531 453211.3.1 Brace and Parenthesis Line-Up Functions 4533---------------------------------------------- 4534 4535The line-up functions here calculate the indentation for braces, 4536parentheses and statements within brace blocks. 4537 4538 -- Function: c-lineup-close-paren 4539 Line up the closing paren under its corresponding open paren if the 4540 open paren is followed by code. If the open paren ends its line, 4541 no indentation is added. E.g.: 4542 4543 main (int, 4544 char ** 4545 ) <- c-lineup-close-paren 4546 4547 and 4548 4549 main ( 4550 int, char ** 4551 ) <- c-lineup-close-paren 4552 4553 As a special case, if a brace block is opened at the same line as 4554 the open parenthesis of the argument list, the indentation is 4555 ‘c-basic-offset’ instead of the open paren column. See 4556 ‘c-lineup-arglist’ for further discussion of this “DWIM” measure. 4557 4558 Works with: All ‘*-close’ symbols. 4559 4560 -- Function: c-lineup-arglist-close-under-paren 4561 Set your ‘arglist-close’ syntactic symbol to this line-up function 4562 so that parentheses that close argument lists will line up under 4563 the parenthesis that opened the argument list. It can also be used 4564 with ‘arglist-cont’ and ‘arglist-cont-nonempty’ to line up all 4565 lines inside a parenthesis under the open paren. 4566 4567 As a special case, if a brace block is opened at the same line as 4568 the open parenthesis of the argument list, the indentation is 4569 ‘c-basic-offset’ only. See ‘c-lineup-arglist’ for further 4570 discussion of this “DWIM” measure. 4571 4572 Works with: Almost all symbols, but are typically most useful on 4573 ‘arglist-close’, ‘brace-list-close’, ‘arglist-cont’ and 4574 ‘arglist-cont-nonempty’. 4575 4576 -- Function: c-indent-one-line-block 4577 Indent a one line block ‘c-basic-offset’ extra. E.g.: 4578 4579 if (n > 0) 4580 {m+=n; n=0;} <- c-indent-one-line-block 4581 <--> c-basic-offset 4582 4583 and 4584 4585 if (n > 0) 4586 { <- c-indent-one-line-block 4587 m+=n; n=0; 4588 } 4589 4590 The block may be surrounded by any kind of parenthesis characters. 4591 ‘nil’ is returned if the line doesn’t start with a one line block, 4592 which makes the function usable in list expressions. 4593 4594 Works with: Almost all syntactic symbols, but most useful on the 4595 ‘-open’ symbols. 4596 4597 -- Function: c-indent-multi-line-block 4598 Indent a multiline block ‘c-basic-offset’ extra. E.g.: 4599 4600 int *foo[] = { 4601 NULL, 4602 {17}, <- c-indent-multi-line-block 4603 4604 and 4605 4606 int *foo[] = { 4607 NULL, 4608 { <- c-indent-multi-line-block 4609 17 4610 }, 4611 <--> c-basic-offset 4612 4613 The block may be surrounded by any kind of parenthesis characters. 4614 ‘nil’ is returned if the line doesn’t start with a multiline block, 4615 which makes the function usable in list expressions. 4616 4617 Works with: Almost all syntactic symbols, but most useful on the 4618 ‘-open’ symbols. 4619 4620 -- Function: c-lineup-runin-statements 4621 Line up statements for coding standards which place the first 4622 statement in a block on the same line as the block opening 4623 brace(1). E.g.: 4624 4625 int main() 4626 { puts ("Hello!"); 4627 return 0; <- c-lineup-runin-statements 4628 } 4629 4630 If there is no statement after the opening brace to align with, 4631 ‘nil’ is returned. This makes the function usable in list 4632 expressions. 4633 4634 Works with: The ‘statement’ syntactic symbol. 4635 4636 -- Function: c-lineup-inexpr-block 4637 This can be used with the in-expression block symbols to indent the 4638 whole block to the column where the construct is started. E.g., 4639 for Java anonymous classes, this lines up the class under the ‘new’ 4640 keyword, and in Pike it lines up the lambda function body under the 4641 ‘lambda’ keyword. Returns ‘nil’ if the block isn’t part of such a 4642 construct. 4643 4644 Works with: ‘inlambda’, ‘inexpr-statement’, ‘inexpr-class’. 4645 4646 -- Function: c-lineup-after-whitesmith-blocks 4647 Compensate for Whitesmith style indentation of blocks. Due to the 4648 way CC Mode calculates anchor positions for normal lines inside 4649 blocks, this function is necessary for those lines to get correct 4650 Whitesmith style indentation. Consider the following examples: 4651 4652 int foo() 4653 { 4654 a; 4655 x; <- c-lineup-after-whitesmith-blocks 4656 4657 int foo() 4658 { 4659 { 4660 a; 4661 } 4662 x; <- c-lineup-after-whitesmith-blocks 4663 4664 The fact that the line with ‘x’ is preceded by a Whitesmith style 4665 indented block in the latter case and not the first should not 4666 affect its indentation. But since CC Mode in cases like this uses 4667 the indentation of the preceding statement as anchor position, the 4668 ‘x’ would in the second case be indented too much if the offset for 4669 ‘statement’ was set simply to zero. 4670 4671 This lineup function corrects for this situation by detecting if 4672 the anchor position is at an open paren character. In that case, 4673 it instead indents relative to the surrounding block just like 4674 ‘c-lineup-whitesmith-in-block’. 4675 4676 Works with: ‘brace-list-entry’, ‘brace-entry-open’, ‘statement’, 4677 ‘arglist-cont’. 4678 4679 -- Function: c-lineup-whitesmith-in-block 4680 Line up lines inside a block in Whitesmith style. It’s done in a 4681 way that works both when the opening brace hangs and when it 4682 doesn’t. E.g.: 4683 4684 something 4685 { 4686 foo; <- c-lineup-whitesmith-in-block 4687 } 4688 4689 and 4690 4691 something { 4692 foo; <- c-lineup-whitesmith-in-block 4693 } 4694 <--> c-basic-offset 4695 4696 In the first case the indentation is kept unchanged, in the second 4697 ‘c-basic-offset’ is added. 4698 4699 Works with: ‘defun-close’, ‘defun-block-intro’, ‘inline-close’, 4700 ‘block-close’, ‘brace-list-close’, ‘brace-list-intro’, 4701 ‘statement-block-intro’, ‘arglist-intro’, ‘arglist-cont-nonempty’, 4702 ‘arglist-close’, and all ‘in*’ symbols, e.g., ‘inclass’ and 4703 ‘inextern-lang’. 4704 4705 ---------- Footnotes ---------- 4706 4707 (1) Run-in style doesn’t really work too well. You might need to 4708write your own custom line-up functions to better support this style. 4709 4710 4711File: ccmode.info, Node: List Line-Up, Next: Operator Line-Up, Prev: Brace/Paren Line-Up, Up: Line-Up Functions 4712 471311.3.2 List Line-Up Functions 4714----------------------------- 4715 4716The line-up functions here calculate the indentation for lines which 4717form lists of items, usually separated by commas. 4718 4719 The function *note c-lineup-arglist-close-under-paren::, which is 4720mainly for indenting a close parenthesis, is also useful for the lines 4721contained within parentheses. 4722 4723 -- Function: c-lineup-arglist 4724 Line up the current argument line under the first argument. 4725 4726 As a special case, if an argument on the same line as the open 4727 parenthesis starts with a brace block opener, the indentation is 4728 ‘c-basic-offset’ only. This is intended as a “DWIM” measure in 4729 cases like macros that contain statement blocks, e.g.: 4730 4731 A_VERY_LONG_MACRO_NAME ({ 4732 some (code, with + long, lines * in[it]); 4733 }); 4734 <--> c-basic-offset 4735 4736 This is motivated partly because it’s more in line with how code 4737 blocks are handled, and partly since it approximates the behavior 4738 of earlier CC Mode versions, which due to inaccurate analysis 4739 tended to indent such cases this way. 4740 4741 Works with: ‘arglist-cont-nonempty’, ‘arglist-close’. 4742 4743 -- Function: c-lineup-arglist-intro-after-paren 4744 Line up a line to just after the open paren of the surrounding 4745 paren or brace block. 4746 4747 Works with: ‘defun-block-intro’, ‘brace-list-intro’, 4748 ‘statement-block-intro’, ‘statement-case-intro’, ‘arglist-intro’. 4749 4750 -- Function: c-lineup-2nd-brace-entry-in-arglist 4751 Line up the second entry of a brace block under the first, when the 4752 first line is also contained in an arglist or an enclosing brace 4753 _on that line_. 4754 4755 I.e. handle something like the following: 4756 4757 set_line (line_t {point_t{0.4, 0.2}, 4758 point_t{0.2, 0.5}, <- brace-list-intro 4759 .....}); 4760 ^ enclosing parenthesis. 4761 4762 The middle line of that example will have a syntactic context with 4763 three syntactic symbols, ‘arglist-cont-nonempty’, 4764 ‘brace-list-intro’, and ‘brace-list-entry’ (*note Brace List 4765 Symbols::). 4766 4767 This function is intended for use in a list. If the construct 4768 being analyzed isn’t like the preceding, the function returns nil. 4769 Otherwise it returns the function 4770 ‘c-lineup-arglist-intro-after-paren’, which the caller then uses to 4771 perform indentation. 4772 4773 Works with: ‘brace-list-intro’. 4774 4775 -- Function: c-lineup-class-decl-init-+ 4776 Line up the second entry of a class (etc.) initializer 4777 ‘c-basic-offset’ characters in from the identifier when: 4778 1. The type is a class, struct, union, etc. (but not an enum); 4779 2. There is a brace block in the type declaration, specifying it; 4780 and 4781 3. The first element of the initializer is on the same line as 4782 its opening brace. 4783 4784 I.e. we have a construct like this: 4785 4786 struct STR { 4787 int i; float f; 4788 } str_1 = {1, 1.7}, 4789 str_2 = {2, 4790 3.1 <- brace-list-intro 4791 }; 4792 <--> c-basic-offset 4793 4794 Note that the syntactic context of the ‘brace-list-intro’ line also 4795 has a syntactic element with the symbol ‘brace-list-entry’ (*note 4796 Brace List Symbols::). 4797 4798 This function is intended for use in a list. If the above 4799 structure isn’t present, the function returns nil, allowing a 4800 different offset specification to indent the line. 4801 4802 Works with: ‘brace-list-intro’. 4803 4804 -- Function: c-lineup-class-decl-init-after-brace 4805 Line up the second entry of a class (etc.) initializer after its 4806 opening brace when: 4807 1. The type is a class, struct, union, etc. (but not an enum); 4808 2. There is a brace block in the type declaration, specifying it; 4809 and 4810 3. The first element of the initializer is on the same line as 4811 its opening brace. 4812 4813 I.e. we have a construct like this: 4814 4815 struct STR { 4816 int i; float f; 4817 } str_1 = {1, 1.7}, 4818 str_2 = {2, 4819 3.1 <- brace-list-intro 4820 }; 4821 4822 Note that the syntactic context of the ‘brace-list-intro’ line also 4823 has a syntactic element with the symbol ‘brace-list-entry’ (*note 4824 Brace List Symbols::). Also note that this function works by 4825 returning the symbol ‘c-lineup-arglist-intro-after-paren’, which 4826 the caller then uses to perform the indentation. 4827 4828 This function is intended for use in a list. If the above 4829 structure isn’t present, the function returns nil, allowing a 4830 different offset specification to indent the line. 4831 4832 Works with: ‘brace-list-intro’. 4833 4834 -- Function: c-lineup-multi-inher 4835 Line up the classes in C++ multiple inheritance clauses and member 4836 initializers under each other. E.g.: 4837 4838 Foo::Foo (int a, int b): 4839 Cyphr (a), 4840 Bar (b) <- c-lineup-multi-inher 4841 4842 and 4843 4844 class Foo 4845 : public Cyphr, 4846 public Bar <- c-lineup-multi-inher 4847 4848 and 4849 4850 Foo::Foo (int a, int b) 4851 : Cyphr (a) 4852 , Bar (b) <- c-lineup-multi-inher 4853 4854 Works with: ‘inher-cont’, ‘member-init-cont’. 4855 4856 -- Function: c-lineup-java-inher 4857 Line up Java implements and extends declarations. If class names 4858 follow on the same line as the ‘implements’/‘extends’ keyword, they 4859 are lined up under each other. Otherwise, they are indented by 4860 adding ‘c-basic-offset’ to the column of the keyword. E.g.: 4861 4862 class Foo 4863 extends 4864 Bar <- c-lineup-java-inher 4865 <--> c-basic-offset 4866 4867 and 4868 4869 class Foo 4870 extends Cyphr, 4871 Bar <- c-lineup-java-inher 4872 4873 Works with: ‘inher-cont’. 4874 4875 -- Function: c-lineup-java-throws 4876 Line up Java throws declarations. If exception names follow on the 4877 same line as the throws keyword, they are lined up under each 4878 other. Otherwise, they are indented by adding ‘c-basic-offset’ to 4879 the column of the ‘throws’ keyword. The ‘throws’ keyword itself is 4880 also indented by ‘c-basic-offset’ from the function declaration 4881 start if it doesn’t hang. E.g.: 4882 4883 int foo() 4884 throws <- c-lineup-java-throws 4885 Bar <- c-lineup-java-throws 4886 <--><--> c-basic-offset 4887 4888 and 4889 4890 int foo() throws Cyphr, 4891 Bar, <- c-lineup-java-throws 4892 Vlod <- c-lineup-java-throws 4893 4894 Works with: ‘func-decl-cont’. 4895 4896 -- Function: c-lineup-template-args 4897 Line up the arguments of a template argument list under each other, 4898 but only in the case where the first argument is on the same line 4899 as the opening ‘<’. 4900 4901 To allow this function to be used in a list expression, ‘nil’ is 4902 returned if there’s no template argument on the first line. 4903 4904 Works with: ‘template-args-cont’. 4905 4906 -- Function: c-lineup-ObjC-method-call 4907 For Objective-C code, line up selector args as Emacs Lisp mode does 4908 with function args: go to the position right after the message 4909 receiver, and if you are at the end of the line, indent the current 4910 line c-basic-offset columns from the opening bracket; otherwise you 4911 are looking at the first character of the first method call 4912 argument, so lineup the current line with it. 4913 4914 Works with: ‘objc-method-call-cont’. 4915 4916 -- Function: c-lineup-ObjC-method-args 4917 For Objective-C code, line up the colons that separate args. The 4918 colon on the current line is aligned with the one on the first 4919 line. 4920 4921 Works with: ‘objc-method-args-cont’. 4922 4923 -- Function: c-lineup-ObjC-method-args-2 4924 Similar to ‘c-lineup-ObjC-method-args’ but lines up the colon on 4925 the current line with the colon on the previous line. 4926 4927 Works with: ‘objc-method-args-cont’. 4928 4929 4930File: ccmode.info, Node: Operator Line-Up, Next: Comment Line-Up, Prev: List Line-Up, Up: Line-Up Functions 4931 493211.3.3 Operator Line-Up Functions 4933--------------------------------- 4934 4935The line-up functions here calculate the indentation for lines which 4936start with an operator, by lining it up with something on the previous 4937line. 4938 4939 -- Function: c-lineup-argcont 4940 Line up a continued argument. E.g.: 4941 4942 foo (xyz, aaa + bbb + ccc 4943 + ddd + eee + fff); <- c-lineup-argcont 4944 4945 Only continuation lines like this are touched, ‘nil’ is returned on 4946 lines which are the start of an argument. 4947 4948 Within a gcc ‘asm’ block, ‘:’ is recognized as an argument 4949 separator, but of course only between operand specifications, not 4950 in the expressions for the operands. 4951 4952 Works with: ‘arglist-cont’, ‘arglist-cont-nonempty’. 4953 4954 -- Function: c-lineup-arglist-operators 4955 Line up lines starting with an infix operator under the open paren. 4956 Return ‘nil’ on lines that don’t start with an operator, to leave 4957 those cases to other line-up functions. Example: 4958 4959 if ( x < 10 4960 || at_limit (x, <- c-lineup-arglist-operators 4961 list) <- c-lineup-arglist-operators returns nil 4962 ) 4963 4964 Since this function doesn’t do anything for lines without an infix 4965 operator you typically want to use it together with some other 4966 lineup settings, e.g., as follows (the ‘arglist-close’ setting is 4967 just a suggestion to get a consistent style): 4968 4969 (c-set-offset 'arglist-cont 4970 '(c-lineup-arglist-operators 0)) 4971 (c-set-offset 'arglist-cont-nonempty 4972 '(c-lineup-arglist-operators c-lineup-arglist)) 4973 (c-set-offset 'arglist-close 4974 '(c-lineup-arglist-close-under-paren)) 4975 4976 Works with: ‘arglist-cont’, ‘arglist-cont-nonempty’. 4977 4978 -- Function: c-lineup-assignments 4979 Line up the current line after the assignment operator on the first 4980 line in the statement. If there isn’t any, return ‘nil’ to allow 4981 stacking with other line-up functions. If the current line 4982 contains an assignment operator too, try to align it with the first 4983 one. 4984 4985 Works with: ‘topmost-intro-cont’, ‘statement-cont’, ‘arglist-cont’, 4986 ‘arglist-cont-nonempty’. 4987 4988 -- Function: c-lineup-math 4989 Like ‘c-lineup-assignments’ but indent with ‘c-basic-offset’ if no 4990 assignment operator was found on the first line. I.e., this 4991 function is the same as specifying a list ‘(c-lineup-assignments 4992 +)’. It’s provided for compatibility with old configurations. 4993 4994 Works with: ‘topmost-intro-cont’, ‘statement-cont’, ‘arglist-cont’, 4995 ‘arglist-cont-nonempty’. 4996 4997 -- Function: c-lineup-cascaded-calls 4998 Line up “cascaded calls” under each other. If the line begins with 4999 ‘->’ or ‘.’ and the preceding line ends with one or more function 5000 calls preceded by the same token, then the arrow is lined up with 5001 the first of those tokens. E.g.: 5002 5003 r = proc->add(17)->add(18) 5004 ->add(19) + <- c-lineup-cascaded-calls 5005 offset; <- c-lineup-cascaded-calls (inactive) 5006 5007 In any other situation ‘nil’ is returned to allow use in list 5008 expressions. 5009 5010 Works with: ‘topmost-intro-cont’, ‘statement-cont’, ‘arglist-cont’, 5011 ‘arglist-cont-nonempty’. 5012 5013 -- Function: c-lineup-streamop 5014 Line up C++ stream operators (i.e., ‘<<’ and ‘>>’). 5015 5016 Works with: ‘stream-op’. 5017 5018 -- Function: c-lineup-string-cont 5019 Line up a continued string under the one it continues. A continued 5020 string in this sense is where a string literal follows directly 5021 after another one. E.g.: 5022 5023 result = prefix + "A message " 5024 "string."; <- c-lineup-string-cont 5025 5026 ‘nil’ is returned in other situations, to allow stacking with other 5027 lineup functions. 5028 5029 Works with: ‘topmost-intro-cont’, ‘statement-cont’, ‘arglist-cont’, 5030 ‘arglist-cont-nonempty’. 5031 5032 5033File: ccmode.info, Node: Comment Line-Up, Next: Misc Line-Up, Prev: Operator Line-Up, Up: Line-Up Functions 5034 503511.3.4 Comment Line-Up Functions 5036-------------------------------- 5037 5038The lineup functions here calculate the indentation for several types of 5039comment structure. 5040 5041 -- Function: c-lineup-C-comments 5042 Line up C block comment continuation lines. Various heuristics are 5043 used to handle most of the common comment styles. Some examples: 5044 5045 /* /** /* 5046 * text * text text 5047 */ */ */ 5048 5049 /* text /* /** 5050 text ** text ** text 5051 */ */ */ 5052 5053 /************************************************** 5054 * text 5055 *************************************************/ 5056 5057 /************************************************** 5058 Free form text comments: 5059 In comments with a long delimiter line at the 5060 start, the indentation is kept unchanged for lines 5061 that start with an empty comment line prefix. The 5062 delimiter line is whatever matches the 5063 comment-start-skip regexp. 5064 **************************************************/ 5065 5066 The style variable ‘c-comment-prefix-regexp’ is used to recognize 5067 the comment line prefix, e.g., the ‘*’ that usually starts every 5068 line inside a comment. 5069 5070 Works with: The ‘c’ syntactic symbol. 5071 5072 -- Function: c-lineup-comment 5073 Line up a comment-only line according to the style variable 5074 ‘c-comment-only-line-offset’. If the comment is lined up with a 5075 comment starter on the previous line, that alignment is preserved. 5076 5077 -- User Option: c-comment-only-line-offset 5078 This style variable specifies the extra offset for the line. 5079 It can contain an integer or a cons cell of the form 5080 5081 (NON-ANCHORED-OFFSET . ANCHORED-OFFSET) 5082 5083 where NON-ANCHORED-OFFSET is the amount of offset given to 5084 non-column-zero anchored lines, and ANCHORED-OFFSET is the 5085 amount of offset to give column-zero anchored lines. Just an 5086 integer as value is equivalent to ‘(VALUE . -1000)’. 5087 5088 Works with: ‘comment-intro’. 5089 5090 -- Function: c-lineup-knr-region-comment 5091 Line up a comment in the “K&R region” with the declaration. That 5092 is the region between the function or class header and the 5093 beginning of the block. E.g.: 5094 5095 int main() 5096 /* Called at startup. */ <- c-lineup-knr-region-comment 5097 { 5098 return 0; 5099 } 5100 5101 Return ‘nil’ if called in any other situation, to be useful in list 5102 expressions. 5103 5104 Works with: ‘comment-intro’. 5105 5106 5107File: ccmode.info, Node: Misc Line-Up, Prev: Comment Line-Up, Up: Line-Up Functions 5108 510911.3.5 Miscellaneous Line-Up Functions 5110-------------------------------------- 5111 5112The line-up functions here are the odds and ends which didn’t fit into 5113any earlier category. 5114 5115 -- Function: c-lineup-dont-change 5116 This lineup function makes the line stay at whatever indentation it 5117 already has; think of it as an identity function for lineups. 5118 5119 Works with: Any syntactic symbol. 5120 5121 -- Function: c-lineup-under-anchor 5122 5123 Line up a line directly underneath its anchor point. This is like 5124 ‘0’, except any previously calculated offset contributions are 5125 disregarded. 5126 5127 Works with: Any syntactic symbol which has an anchor point. 5128 5129 -- Function: c-lineup-cpp-define 5130 Line up macro continuation lines according to the indentation of 5131 the construct preceding the macro. E.g.: 5132 5133 const char msg[] = <- The beginning of the preceding construct. 5134 \"Some text.\"; 5135 5136 #define X(A, B) \ 5137 do { \ <- c-lineup-cpp-define 5138 printf (A, B); \ 5139 } while (0) 5140 5141 and: 5142 5143 int dribble() { 5144 if (!running) <- The beginning of the preceding construct. 5145 error(\"Not running!\"); 5146 5147 #define X(A, B) \ 5148 do { \ <- c-lineup-cpp-define 5149 printf (A, B); \ 5150 } while (0) 5151 5152 If ‘c-syntactic-indentation-in-macros’ is non-‘nil’, the function 5153 returns the relative indentation to the macro start line to allow 5154 accumulation with other offsets. E.g., in the following cases, 5155 ‘cpp-define-intro’ is combined with the ‘statement-block-intro’ 5156 that comes from the ‘do {’ that hangs on the ‘#define’ line: 5157 5158 const char msg[] = 5159 \"Some text.\"; 5160 5161 #define X(A, B) do { \ 5162 printf (A, B); \ <- c-lineup-cpp-define 5163 this->refs++; \ 5164 } while (0) <- c-lineup-cpp-define 5165 5166 and: 5167 5168 int dribble() { 5169 if (!running) 5170 error(\"Not running!\"); 5171 5172 #define X(A, B) do { \ 5173 printf (A, B); \ <- c-lineup-cpp-define 5174 this->refs++; \ 5175 } while (0) <- c-lineup-cpp-define 5176 5177 The relative indentation returned by ‘c-lineup-cpp-define’ is zero 5178 and two, respectively, on the two lines in each of these examples. 5179 They are then added to the two column indentation that 5180 ‘statement-block-intro’ gives in both cases here. 5181 5182 If the relative indentation is zero, then ‘nil’ is returned 5183 instead. That is useful in a list expression to specify the 5184 default indentation on the top level. 5185 5186 If ‘c-syntactic-indentation-in-macros’ is ‘nil’ then this function 5187 keeps the current indentation, except for empty lines (ignoring the 5188 ending backslash) where it takes the indentation from the closest 5189 preceding nonempty line in the macro. If there’s no such line in 5190 the macro then the indentation is taken from the construct 5191 preceding it, as described above. 5192 5193 Works with: ‘cpp-define-intro’. 5194 5195 -- Function: c-lineup-gcc-asm-reg 5196 Line up a gcc asm register under one on a previous line. 5197 5198 asm ("foo %1, %0\n" 5199 "bar %0, %1" 5200 : "=r" (w), 5201 "=r" (x) 5202 : "0" (y), 5203 "1" (z)); 5204 5205 The ‘x’ line is aligned to the text after the ‘:’ on the ‘w’ line, 5206 and similarly ‘z’ under ‘y’. 5207 5208 This is done only in an ‘asm’ or ‘__asm__’ block, and only to those 5209 lines mentioned. Anywhere else ‘nil’ is returned. The usual 5210 arrangement is to have this routine as an extra feature at the 5211 start of arglist lineups, e.g.: 5212 5213 (c-lineup-gcc-asm-reg c-lineup-arglist) 5214 5215 Works with: ‘arglist-cont’, ‘arglist-cont-nonempty’. 5216 5217 -- Function: c-lineup-topmost-intro-cont 5218 Line up declaration continuation lines zero or one indentation 5219 step(1). For lines preceding a definition, zero is used. For 5220 other lines, ‘c-basic-offset’ is added to the indentation. E.g.: 5221 5222 int 5223 neg (int i) <- c-lineup-topmost-intro-cont 5224 { 5225 return -i; 5226 } 5227 5228 and 5229 5230 struct 5231 larch <- c-lineup-topmost-intro-cont 5232 { 5233 double height; 5234 } 5235 the_larch, <- c-lineup-topmost-intro-cont 5236 another_larch; <- c-lineup-topmost-intro-cont 5237 <--> c-basic-offset 5238 5239 and 5240 5241 struct larch 5242 the_larch, <- c-lineup-topmost-intro-cont 5243 another_larch; <- c-lineup-topmost-intro-cont 5244 5245 Works with: ‘topmost-intro-cont’. 5246 5247 ---------- Footnotes ---------- 5248 5249 (1) This function is mainly provided to mimic the behavior of CC Mode 52505.28 and earlier where this case wasn’t handled consistently so that 5251those lines could be analyzed as either topmost-intro-cont or 5252statement-cont. It’s used for ‘topmost-intro-cont’ by default, but you 5253might consider using ‘+’ instead. 5254 5255 5256File: ccmode.info, Node: Custom Line-Up, Next: Other Indentation, Prev: Line-Up Functions, Up: Customizing Indentation 5257 525811.4 Custom Line-Up Functions 5259============================= 5260 5261The most flexible way to customize indentation is by writing custom 5262line-up functions, and associating them with specific syntactic symbols 5263(*note c-offsets-alist::). Depending on the effect you want, it might 5264be better to write a ‘c-special-indent-hook’ function rather than a 5265line-up function (*note Other Indentation::). 5266 5267 CC Mode comes with an extensive set of predefined line-up functions, 5268not all of which are used by the default styles. So there’s a good 5269chance the function you want already exists. *Note Line-Up Functions::, 5270for a list of them. If you write your own line-up function, it’s 5271probably a good idea to start working from one of these predefined 5272functions, which can be found in the file ‘cc-align.el’. If you have 5273written a line-up function that you think is generally useful, you’re 5274very welcome to contribute it; please contact <bug-cc-mode@gnu.org>. 5275 5276 Line-up functions are passed a single argument, the syntactic element 5277(see below). At the time of the call, point will be somewhere on the 5278line being indented. The return value is a ‘c-offsets-alist’ offset 5279specification: for example, an integer, a symbol such as ‘+’, a vector, 5280‘nil’(1), or even another line-up function. Full details of these are 5281in *note c-offsets-alist::. 5282 5283 Line-up functions must not move point or change the content of the 5284buffer (except temporarily). They are however allowed to do “hidden 5285buffer changes”, i.e., setting text properties for caching purposes etc. 5286Buffer undo recording is disabled while they run. 5287 5288 The syntactic element passed as the parameter to a line-up function 5289is a cons cell of the form 5290 5291 (SYNTACTIC-SYMBOL . ANCHOR-POSITION) 5292 5293where SYNTACTIC-SYMBOL is the symbol that the function was called for, 5294and ANCHOR-POSITION is the anchor position (if any) for the construct 5295that triggered the syntactic symbol (*note Syntactic Analysis::). This 5296cons cell is how the syntactic element of a line used to be represented 5297in CC Mode 5.28 and earlier. Line-up functions are still passed this 5298cons cell, so as to preserve compatibility with older configurations. 5299In the future, we may decide to convert to using the full list 5300format—you can prepare your setup for this by using the access functions 5301(‘c-langelem-sym’, etc.) described below. 5302 5303 Some syntactic symbols, e.g., ‘arglist-cont-nonempty’, have more info 5304in the syntactic element: typically other positions that can be 5305interesting besides the anchor position. That info can’t be accessed 5306through the passed argument, which is a cons cell. Instead, you can get 5307this information from the variable ‘c-syntactic-element’, which is 5308dynamically bound to the complete syntactic element. The variable 5309‘c-syntactic-context’ might also be useful: it gets dynamically bound to 5310the complete syntactic context. *Note Custom Braces::. 5311 5312 CC Mode provides a few functions to access parts of syntactic 5313elements in a more abstract way. Besides making the code easier to 5314read, they also hide the difference between the old cons cell form used 5315in the line-up function argument and the new list form used in 5316‘c-syntactic-element’ and everywhere else. The functions are: 5317 5318 -- Function: c-langelem-sym langelem 5319 Return the syntactic symbol in LANGELEM. 5320 5321 -- Function: c-langelem-pos langelem 5322 Return the anchor position in LANGELEM, or ‘nil’ if there is none. 5323 5324 -- Function: c-langelem-col langelem &optional preserve-point 5325 Return the column of the anchor position in LANGELEM. Also move 5326 the point to that position unless PRESERVE-POINT is non-‘nil’. 5327 5328 -- Function: c-langelem-2nd-pos langelem 5329 Return the secondary position in LANGELEM, or ‘nil’ if there is 5330 none. 5331 5332 Note that the return value of this function is always ‘nil’ if 5333 LANGELEM is in the old cons cell form. Thus this function is only 5334 meaningful when used on syntactic elements taken from 5335 ‘c-syntactic-element’ or ‘c-syntactic-context’. 5336 5337 Sometimes you may need to use the syntactic context of a line other 5338than the one being indented. You can determine this by (temporarily) 5339moving point onto this line and calling ‘c-guess-basic-syntax’ (*note 5340Syntactic Analysis::). 5341 5342 Custom line-up functions can be as simple or as complex as you like, 5343and any syntactic symbol that appears in ‘c-offsets-alist’ can have a 5344custom line-up function associated with it. 5345 5346 ---------- Footnotes ---------- 5347 5348 (1) Returning ‘nil’ is useful when the offset specification for a 5349syntactic element is a list containing the line-up function (*note 5350c-offsets-alist::). 5351 5352 5353File: ccmode.info, Node: Other Indentation, Prev: Custom Line-Up, Up: Customizing Indentation 5354 535511.5 Other Special Indentations 5356=============================== 5357 5358To configure macros which you invoke without a terminating ‘;’, *note 5359Macros with ;::. 5360 5361 Here are the remaining odds and ends regarding indentation: 5362 5363 -- User Option: c-label-minimum-indentation 5364 In ‘gnu’ style (*note Built-in Styles::), a minimum indentation is 5365 imposed on lines inside code blocks. This minimum indentation is 5366 controlled by this style variable. The default value is 1. 5367 5368 It’s the function ‘c-gnu-impose-minimum’ that enforces this minimum 5369 indentation. It must be present on ‘c-special-indent-hook’ to 5370 work. 5371 5372 -- User Option: c-special-indent-hook 5373 This style variable is a standard hook variable that is called 5374 after every line is indented by CC Mode. It is called only if 5375 ‘c-syntactic-indentation’ is non-‘nil’ (which it is by default 5376 (*note Indentation Engine Basics::)). You can put a function on 5377 this hook to do any special indentation or ad hoc line adjustments 5378 your style dictates, such as adding extra indentation to 5379 constructors or destructor declarations in a class definition, etc. 5380 Sometimes it is better to write a custom Line-up Function instead 5381 (*note Custom Line-Up::). 5382 5383 When the indentation engine calls this hook, the variable 5384 ‘c-syntactic-context’ is bound to the current syntactic context 5385 (i.e., what you would get by typing ‘C-c C-s’ on the source line. 5386 *Note Custom Braces::.). Note that you should not change point or 5387 mark inside a ‘c-special-indent-hook’ function, i.e., you’ll 5388 probably want to wrap your function in a ‘save-excursion’(1). 5389 5390 Setting ‘c-special-indent-hook’ in style definitions is handled 5391 slightly differently from other variables—A style can only add 5392 functions to this hook, not remove them. *Note Style Variables::. 5393 5394 ---------- Footnotes ---------- 5395 5396 (1) The numerical value returned by ‘point’ will change if you change 5397the indentation of the line within a ‘save-excursion’ form, but point 5398itself will still be over the same piece of text. 5399 5400 5401File: ccmode.info, Node: Custom Macros, Next: Odds and Ends, Prev: Customizing Indentation, Up: Top 5402 540312 Customizing Macros 5404********************* 5405 5406Preprocessor macros in C, C++, and Objective C (introduced by ‘#define’) 5407have a syntax different from the main language—for example, a macro 5408declaration is not terminated by a semicolon, and if it is more than a 5409line long, line breaks in it must be escaped with backslashes. CC Mode 5410has some commands to manipulate these, see *note Macro Backslashes::. 5411 5412 Normally, the lines in a multi-line macro are indented relative to 5413each other as though they were code. You can suppress this behavior by 5414setting the following user option: 5415 5416 -- User Option: c-syntactic-indentation-in-macros 5417 Enable syntactic analysis inside macros, which is the default. If 5418 this is ‘nil’, all lines inside macro definitions are analyzed as 5419 ‘cpp-macro-cont’. 5420 5421 Because a macro can expand into anything at all, near where one is 5422invoked CC Mode can only indent and fontify code heuristically. 5423Sometimes it gets it wrong. Usually you should try to design your 5424macros so that they “look like ordinary code” when you invoke them. 5425However, two situations are so common that CC Mode handles them 5426specially: that is when certain macros needn’t (or mustn’t) be followed 5427by a ‘;’, and when certain macros (or compiler directives) expand to 5428nothing. You need to configure CC Mode to handle these macros properly, 5429see *note Macros with ;:: and *note Noise Macros::. 5430 5431* Menu: 5432 5433* Macro Backslashes:: 5434* Macros with ;:: 5435* Noise Macros:: 5436 5437 5438File: ccmode.info, Node: Macro Backslashes, Next: Macros with ;, Prev: Custom Macros, Up: Custom Macros 5439 544012.1 Customizing Macro Backslashes 5441================================== 5442 5443CC Mode provides some tools to help keep the line continuation 5444backslashes in macros neat and tidy. Their precise action is customized 5445with these variables: 5446 5447 -- User Option: c-backslash-column 5448 -- User Option: c-backslash-max-column 5449 These variables control the alignment columns for line continuation 5450 backslashes in multiline macros. They are used by the functions 5451 that automatically insert or align such backslashes, e.g., 5452 ‘c-backslash-region’ and ‘c-context-line-break’. 5453 5454 ‘c-backslash-column’ specifies the minimum column for the 5455 backslashes. If any line in the macro goes past this column, then 5456 the next tab stop (i.e., next multiple of ‘tab-width’) in that line 5457 is used as the alignment column for all the backslashes, so that 5458 they remain in a single column. However, if any lines go past 5459 ‘c-backslash-max-column’ then the backslashes in the rest of the 5460 macro will be kept at that column, so that the lines which are too 5461 long “stick out” instead. 5462 5463 Don’t ever set these variables to ‘nil’. If you want to disable 5464 the automatic alignment of backslashes, use 5465 ‘c-auto-align-backslashes’. 5466 5467 -- User Option: c-auto-align-backslashes 5468 Align automatically inserted line continuation backslashes if 5469 non-‘nil’. When line continuation backslashes are inserted 5470 automatically for line breaks in multiline macros, e.g., by 5471 ‘c-context-line-break’, they are aligned with the other backslashes 5472 in the same macro if this flag is set. 5473 5474 If ‘c-auto-align-backslashes’ is ‘nil’, automatically inserted 5475 backslashes are preceded by a single space, and backslashes get 5476 aligned only when you explicitly invoke the command 5477 ‘c-backslash-region’ (‘C-c C-\’). 5478 5479 5480File: ccmode.info, Node: Macros with ;, Next: Noise Macros, Prev: Macro Backslashes, Up: Custom Macros 5481 548212.2 Macros with semicolons 5483=========================== 5484 5485Macros which needn’t (or mustn’t) be followed by a semicolon when you 5486invoke them, “macros with semicolons”, are very common. These can cause 5487CC Mode to parse the next line wrongly as a ‘statement-cont’ (*note 5488Function Symbols::) and thus mis-indent it. At the top level, a macro 5489invocation before a defun start can cause, for example, 5490‘c-beginning-of-defun’ (‘C-M-a’) not to find the correct start of the 5491current function. 5492 5493 You can prevent these by specifying which macros have semicolons. It 5494doesn’t matter whether or not such a macro has a parameter list: 5495 5496 -- User Option: c-macro-names-with-semicolon 5497 This buffer-local variable specifies which macros have semicolons. 5498 After setting its value, you need to call 5499 ‘c-make-macro-with-semi-re’ for it to take effect. It should be 5500 set to one of these values: 5501 5502 nil 5503 There are no macros with semicolons. 5504 a list of strings 5505 Each string is the name of a macro with a semicolon. Only 5506 valid ‘#define’ names are allowed here. For example, to set 5507 the default value, you could write the following into your 5508 ‘.emacs’: 5509 5510 (setq c-macro-names-with-semicolon 5511 '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS")) 5512 5513 a regular expression 5514 This matches each symbol which is a macro with a semicolon. 5515 It must not match any string which isn’t a valid ‘#define’ 5516 name. For example: 5517 5518 (setq c-macro-names-with-semicolon 5519 "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>") 5520 5521 -- Function: c-make-macro-with-semi-re 5522 Call this (non-interactive) function, which sets internal 5523 variables, each time you change the value of 5524 ‘c-macro-names-with-semicolon’ after the major mode function has 5525 run. It takes no arguments, and its return value has no meaning. 5526 This function is called by CC Mode’s initialization code, after the 5527 mode hooks have run. 5528 5529 5530File: ccmode.info, Node: Noise Macros, Prev: Macros with ;, Up: Custom Macros 5531 553212.3 Noise Macros 5533================= 5534 5535In CC Mode, “noise macros” are macros which expand to nothing, or 5536compiler directives (such as GCC’s ‘__attribute__’) which play no part 5537in the syntax of the C (etc.) language. Some noise macros are followed 5538by arguments in parentheses (possibly optionally), others are not. 5539 5540 Noise macros can easily confuse CC Mode’s analysis of function 5541headers, causing them to be mis-fontified, or even mis-indented. You 5542can prevent this confusion by specifying the identifiers which 5543constitute noise macros. 5544 5545 -- User Option: c-noise-macro-names 5546 This variable is a list of names of noise macros which never have 5547 parenthesized arguments. Each element is a string, and must be a 5548 valid identifier. Alternatively, the variable may be a regular 5549 expression which matches the names of such macros. Such a noise 5550 macro is treated as whitespace by CC Mode. It must not also be in, 5551 or be matched by ‘c-noise-macro-with-parens-names’. 5552 5553 -- User Option: c-noise-macro-with-parens-names 5554 This variable is a list of names of noise macros which optionally 5555 have arguments in parentheses. Each element of the list is a 5556 string, and must be a valid identifier. Alternatively, the 5557 variable may be a regular expression which matches the names of 5558 such macros. Such a noise macro must not also be in, or be matched 5559 by ‘c-noise-macro-names’. For performance reasons, such a noise 5560 macro, including any parenthesized arguments, is specially handled, 5561 but it is only handled when used in declaration contexts(1). 5562 5563 The two compiler directives ‘__attribute__’ and ‘__declspec’ have 5564 traditionally been handled specially in CC Mode; for example they 5565 are fontified with font-lock-keyword-face. You don’t need to 5566 include these directives in ‘c-noise-macro-with-parens-names’, but 5567 doing so is OK. 5568 5569 -- Function: c-make-noise-macro-regexps 5570 Call this (non-interactive) function, which sets internal 5571 variables, on changing the value of ‘c-noise-macro-names’ or 5572 ‘c-noise-macro-with-parens-names’ after the major mode’s function 5573 has run. This function is called by CC Mode’s initialization code, 5574 after the mode hooks have run. 5575 5576 ---------- Footnotes ---------- 5577 5578 (1) If this restriction causes your project difficulties, please get 5579in touch with <bug-cc-mode@gnu.org>. 5580 5581 5582File: ccmode.info, Node: Odds and Ends, Next: Sample Init File, Prev: Custom Macros, Up: Top 5583 558413 Odds and Ends 5585**************** 5586 5587The stuff that didn’t fit in anywhere else is documented here. 5588 5589 -- User Option: c-require-final-newline 5590 Controls whether a final newline is enforced when the file is 5591 saved. The value is an association list that for each language 5592 mode specifies the value to give to ‘require-final-newline’ (*note 5593 (elisp)Saving Buffers::) at mode initialization. If a language 5594 isn’t present on the association list, CC Mode won’t touch 5595 ‘require-final-newline’ in buffers for that language. 5596 5597 The default is to set ‘require-final-newline’ to ‘t’ in the 5598 languages that mandate that source files should end with newlines. 5599 These are C, C++ and Objective-C. 5600 5601 -- User Option: c-echo-syntactic-information-p 5602 If non-‘nil’, the syntactic analysis for the current line is shown 5603 in the echo area when it’s indented (unless 5604 ‘c-syntactic-indentation’ is ‘nil’). That’s useful when finding 5605 out which syntactic symbols to modify to get the indentation you 5606 want. 5607 5608 -- User Option: c-report-syntactic-errors 5609 If non-‘nil’, certain syntactic errors are reported with a ding and 5610 a message, for example when an ‘else’ is indented for which there 5611 is no corresponding ‘if’. 5612 5613 Note however that CC Mode doesn’t make any special effort to check 5614 for syntactic errors; that’s the job of the compiler. The reason 5615 it can report cases like the one above is that it can’t find the 5616 correct anchoring position to indent the line in that case. 5617 5618 5619File: ccmode.info, Node: Sample Init File, Next: Performance Issues, Prev: Odds and Ends, Up: Top 5620 5621Appendix A Sample Init File 5622*************************** 5623 5624Here’s a sample .emacs file fragment that might help you along the way. 5625Just copy this region and paste it into your .emacs file. You might 5626want to change some of the actual values. 5627 5628;; Make a non-standard key binding. We can put this in 5629;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, 5630;; inherit from it. 5631(defun my-c-initialization-hook () 5632 (define-key c-mode-base-map "\C-m" 'c-context-line-break)) 5633(add-hook 'c-initialization-hook 'my-c-initialization-hook) 5634 5635;; offset customizations not in my-c-style 5636;; This will take precedence over any setting of the syntactic symbol 5637;; made by a style. 5638(setq c-offsets-alist '((member-init-intro . ++))) 5639 5640;; Create my personal style. 5641(defconst my-c-style 5642 '((c-tab-always-indent . t) 5643 (c-comment-only-line-offset . 4) 5644 (c-hanging-braces-alist . ((substatement-open after) 5645 (brace-list-open))) 5646 (c-hanging-colons-alist . ((member-init-intro before) 5647 (inher-intro) 5648 (case-label after) 5649 (label after) 5650 (access-label after))) 5651 (c-cleanup-list . (scope-operator 5652 empty-defun-braces 5653 defun-close-semi)) 5654 (c-offsets-alist . ((arglist-close . c-lineup-arglist) 5655 (substatement-open . 0) 5656 (case-label . 4) 5657 (block-open . 0) 5658 (knr-argdecl-intro . -))) 5659 (c-echo-syntactic-information-p . t)) 5660 "My C Programming Style") 5661(c-add-style "PERSONAL" my-c-style) 5662 5663;; Customizations for all modes in CC Mode. 5664(defun my-c-mode-common-hook () 5665 ;; set my personal style for the current buffer 5666 (c-set-style "PERSONAL") 5667 ;; other customizations 5668 (setq tab-width 8 5669 ;; this will make sure spaces are used instead of tabs 5670 indent-tabs-mode nil) 5671 ;; we like auto-newline, but not hungry-delete 5672 (c-toggle-auto-newline 1)) 5673(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) 5674 5675 5676File: ccmode.info, Node: Performance Issues, Next: Limitations and Known Bugs, Prev: Sample Init File, Up: Top 5677 5678Appendix B Performance Issues 5679***************************** 5680 5681C and its derivative languages are highly complex creatures. Often, 5682ambiguous code situations arise that require CC Mode to scan large 5683portions of the buffer to determine syntactic context. Such 5684pathological code can cause CC Mode to perform fairly badly. This 5685section gives some insight in how CC Mode operates, how that interacts 5686with some coding styles, and what you can use to improve performance. 5687 5688 The overall goal is that CC Mode shouldn’t be overly slow (i.e., take 5689more than a fraction of a second) in any interactive operation. I.e., 5690it’s tuned to limit the maximum response time in single operations, 5691which is sometimes at the expense of batch-like operations like 5692reindenting whole blocks. If you find that CC Mode gradually gets 5693slower and slower in certain situations, perhaps as the file grows in 5694size or as the macro or comment you’re editing gets bigger, then chances 5695are that something isn’t working right. You should consider reporting 5696it, unless it’s something that’s mentioned in this section. 5697 5698 Because CC Mode has to scan the buffer backwards from the current 5699insertion point, and because C’s syntax is fairly difficult to parse in 5700the backwards direction, CC Mode often tries to find the nearest 5701position higher up in the buffer from which to begin a forward scan 5702(it’s typically an opening or closing parenthesis of some kind). The 5703farther this position is from the current insertion point, the slower it 5704gets. 5705 5706 In earlier versions of CC Mode, we used to recommend putting the 5707opening brace of a top-level construct(1) into the leftmost column. 5708Earlier still, this used to be a rigid Emacs constraint, as embodied in 5709the ‘beginning-of-defun’ function. CC Mode now caches syntactic 5710information much better, so that the delay caused by searching for such 5711a brace when it’s not in column 0 is minimal, except perhaps when you’ve 5712just moved a long way inside the file. 5713 5714 A special note about ‘defun-prompt-regexp’ in Java mode: The common 5715style is to hang the opening braces of functions and classes on the 5716right side of the line, and that doesn’t work well with the Emacs 5717approach. CC Mode comes with a constant ‘c-Java-defun-prompt-regexp’ 5718which tries to define a regular expression usable for this style, but 5719there are problems with it. In some cases it can cause 5720‘beginning-of-defun’ to hang(2). For this reason, it is not used by 5721default, but if you feel adventurous, you can set ‘defun-prompt-regexp’ 5722to it in your mode hook. In any event, setting and relying on 5723‘defun-prompt-regexp’ will definitely slow things down because (X)Emacs 5724will be doing regular expression searches a lot, so you’ll probably be 5725taking a hit either way! 5726 5727 CC Mode maintains a cache of the opening parentheses of the blocks 5728surrounding the point, and it adapts that cache as the point is moved 5729around. That means that in bad cases it can take noticeable time to 5730indent a line in a new surrounding, but after that it gets fast as long 5731as the point isn’t moved far off. The farther the point is moved, the 5732less useful is the cache. Since editing typically is done in “chunks” 5733rather than on single lines far apart from each other, the cache 5734typically gives good performance even when the code doesn’t fit the 5735Emacs approach to finding the defun starts. 5736 5737 XEmacs users can set the variable 5738‘c-enable-xemacs-performance-kludge-p’ to non-‘nil’. This tells CC Mode 5739to use XEmacs-specific built-in functions which, in some circumstances, 5740can locate the top-most opening brace much more quickly than 5741‘beginning-of-defun’. Preliminary testing has shown that for styles 5742where these braces are hung (e.g., most JDK-derived Java styles), this 5743hack can improve performance of the core syntax parsing routines from 3 5744to 60 times. However, for styles which _do_ conform to Emacs’s 5745recommended style of putting top-level braces in column zero, this hack 5746can degrade performance by about as much. Thus this variable is set to 5747‘nil’ by default, since the Emacs-friendly styles should be more common 5748(and encouraged!). Note that this variable has no effect in Emacs since 5749the necessary built-in functions don’t exist (in Emacs 22.1 as of this 5750writing in February 2007). 5751 5752 Text properties are used to speed up skipping over syntactic 5753whitespace, i.e., comments and preprocessor directives. Indenting a 5754line after a huge macro definition can be slow the first time, but after 5755that the text properties are in place and it should be fast (even after 5756you’ve edited other parts of the file and then moved back). 5757 5758 Font locking can be a CPU hog, especially the font locking done on 5759decoration level 3 which tries to be very accurate. Note that that 5760level is designed to be used with a font lock support mode that only 5761fontifies the text that’s actually shown, i.e., Lazy Lock or 5762Just-in-time Lock mode, so make sure you use one of them. Fontification 5763of a whole buffer with some thousand lines can often take over a minute. 5764That is a known weakness; the idea is that it never should happen. 5765 5766 The most effective way to speed up font locking is to reduce the 5767decoration level to 2 by setting ‘font-lock-maximum-decoration’ 5768appropriately. That level is designed to be as pretty as possible 5769without sacrificing performance. *Note Font Locking Preliminaries::, 5770for more info. 5771 5772 ---------- Footnotes ---------- 5773 5774 (1) E.g., a function in C, or outermost class definition in C++ or 5775Java. 5776 5777 (2) This has been observed in Emacs 19.34 and XEmacs 19.15. 5778 5779 5780File: ccmode.info, Node: Limitations and Known Bugs, Next: FAQ, Prev: Performance Issues, Up: Top 5781 5782Appendix C Limitations and Known Bugs 5783************************************* 5784 5785 • CC Mode doesn’t support trigraphs. (These are character sequences 5786 such as ‘??(’, which represents ‘[’. They date from a time when 5787 some character sets didn’t have all the characters that C needs, 5788 and are now utterly obsolete.) 5789 5790 • There is no way to apply auto newline settings (*note 5791 Auto-newlines::) on already typed lines. That’s only a feature to 5792 ease interactive editing. 5793 5794 To generalize this issue a bit: CC Mode is not intended to be used 5795 as a reformatter for old code in some more or less batch-like way. 5796 With the exception of some functions like ‘c-indent-region’, it’s 5797 only geared to be used interactively to edit new code. There’s 5798 currently no intention to change this goal. 5799 5800 If you want to reformat old code, you’re probably better off using 5801 some other tool instead, e.g., *note GNU indent: (indent)Top, which 5802 has more powerful reformatting capabilities than CC Mode. 5803 5804 • The support for C++ templates (in angle brackets) is not yet 5805 complete. When a non-nested template is used in a declaration, CC 5806 Mode indents it and font-locks it OK. Templates used in 5807 expressions, and nested templates do not fare so well. Sometimes a 5808 workaround is to refontify the expression after typing the closing 5809 ‘>’. 5810 5811 • In a “k&r region” (the part of an old-fashioned C function 5812 declaration which specifies the types of its parameters, coming 5813 between the parameter list and the opening brace), there should be 5814 at most 20 top-level parenthesis and bracket pairs. This limit has 5815 been imposed for performance reasons. If it is violated, the 5816 source file might be incorrectly indented or fontified. 5817 5818 • On loading CC Mode, sometimes this error message appears: 5819 5820 File mode specification error: (void-variable c-font-lock-keywords-3) 5821 5822 This is due to a bug in the function ‘eval-after-load’ in some 5823 versions of (X)Emacs. It can manifest itself when there is a 5824 symbolic link in the path of the directory which contains (X)Emacs. 5825 As a workaround, put the following into your ‘.emacs’ file, fairly 5826 early on: 5827 5828 (defun my-load-cc-fonts () 5829 (require "cc-fonts")) 5830 (add-hook 'c-initialization-hook 'my-load-cc-fonts) 5831 5832 5833File: ccmode.info, Node: FAQ, Next: Updating CC Mode, Prev: Limitations and Known Bugs, Up: Top 5834 5835Appendix D Frequently Asked Questions 5836************************************* 5837 5838 • _How can I change the indent level from 4 spaces to 2 spaces?_ 5839 5840 Set the variable ‘c-basic-offset’. *Note Getting Started::. 5841 5842 • _Why does/doesn’t the ‘<RET>’ key indent the new line?_ 5843 5844 Emacs’s convention used to be that ‘RET’ just adds a newline, and 5845 that ‘C-j’ adds a newline and indents it. In Emacs-24.4, this 5846 convention was reversed. 5847 5848 If you use an older Emacs and you want ‘<RET>’ do this too, add 5849 this to your ‘c-initialization-hook’: 5850 5851 (define-key c-mode-base-map "\C-m" 'c-context-line-break) 5852 5853 *Note Getting Started::. This was a very common question. 5854 5855 • _How do I get block comments in my C++ files?_ 5856 5857 Interactively, change the comment style with ‘C-c C-k’. *Note 5858 Minor Modes::. 5859 5860 To configure this setting, say, for files within the gdb project, 5861 you could amend your C++ Mode hook like this: 5862 5863 (defun my-c++-mode-hook () 5864 (if (string-match "/gdb/" (buffer-file-name)) 5865 (c-toggle-comment-style 1))) 5866 (add-hook 'c++-mode-hook 'my-c++-mode-hook) 5867 5868 • _How do I stop my C++ lambda expressions being indented way over to 5869 the right?_ 5870 5871 This is now the default, so you don’t need to do anything. To 5872 restore the previous default, indenting lambda expressions to the 5873 right of the constructs which introduce them, change the offset 5874 associated with ‘inlambda’ from 0 to ‘c-lineup-inexpr-block’. For 5875 example, if you are setting offsets in a hook function you might 5876 include the following line: 5877 5878 (c-set-offset 'inlambda 'c-lineup-inexpr-block) 5879 5880 For details of the different ways you can make this setting, *note 5881 Config Basics::. 5882 5883 • _How do I stop my code jumping all over the place when I type?_ 5884 5885 Deactivate “electric minor mode” with ‘C-c C-l’. *Note Getting 5886 Started::. 5887 5888 • _How do I reindent the whole file?_ 5889 5890 Visit the file and hit ‘C-x h’ to mark the whole buffer. Then hit 5891 ‘C-M-\’. *Note Indentation Commands::. 5892 5893 • _How do I reindent the current block?_ 5894 5895 First move to the brace which opens the block with ‘C-M-u’, then 5896 reindent that expression with ‘C-M-q’. *Note Indentation 5897 Commands::. 5898 5899 • _I put ‘(c-set-offset 'substatement-open 0)’ in my ‘.emacs’ file 5900 but I get an error saying that ‘c-set-offset’’s function definition 5901 is void. What’s wrong?_ 5902 5903 This means that CC Mode hasn’t yet been loaded into your Emacs 5904 session by the time the ‘c-set-offset’ call is reached, most likely 5905 because CC Mode is being autoloaded. Instead of putting the 5906 ‘c-set-offset’ line in your top-level ‘.emacs’ file, put it in your 5907 ‘c-initialization-hook’ (*note CC Hooks::), or simply modify 5908 ‘c-offsets-alist’ directly: 5909 5910 (setq c-offsets-alist '((substatement-open . 0))) 5911 5912 • _I have an open paren character at column zero inside a comment or 5913 multiline string literal, and it causes the fontification and/or 5914 indentation to go haywire. What gives?_ 5915 5916 It’s due to the ad-hoc rule in (X)Emacs that such open parens 5917 always start defuns (which translates to functions, classes, 5918 namespaces or any other top-level block constructs in the CC Mode 5919 languages). *Note (emacs)Left Margin Paren::, for details (*Note 5920 (emacs)Defuns::, in the Emacs 20 manual). 5921 5922 This heuristic is built into the core syntax analysis routines in 5923 (X)Emacs, so it’s not really a CC Mode issue. However, in Emacs 5924 21.1 it became possible to turn it off(1) and CC Mode does so there 5925 since it’s got its own system to keep track of blocks. 5926 5927 ---------- Footnotes ---------- 5928 5929 (1) Using the variable ‘open-paren-in-column-0-is-defun-start’. 5930 5931 5932File: ccmode.info, Node: Updating CC Mode, Next: Mailing Lists and Bug Reports, Prev: FAQ, Up: Top 5933 5934Appendix E Getting the Latest CC Mode Release 5935********************************************* 5936 5937CC Mode has been standard with all versions of Emacs since 19.34 and of 5938XEmacs since 19.16. 5939 5940 Due to release schedule skew, it is likely that all of these Emacsen 5941have old versions of CC Mode and so should be upgraded. Access to the 5942CC Mode source code, as well as more detailed information on Emacsen 5943compatibility, etc. are all available on the web site: 5944 5945 <http://cc-mode.sourceforge.net/> 5946 5947 5948File: ccmode.info, Node: Mailing Lists and Bug Reports, Next: GNU Free Documentation License, Prev: Updating CC Mode, Up: Top 5949 5950Appendix F Mailing Lists and Submitting Bug Reports 5951*************************************************** 5952 5953To report bugs, use the ‘C-c C-b’ (bound to ‘c-submit-bug-report’) 5954command. This provides vital information we need to reproduce your 5955problem. Make sure you include a concise, but complete code example. 5956Please try to boil your example down to just the essential code needed 5957to reproduce the problem, and include an exact recipe of steps needed to 5958expose the bug. Be especially sure to include any code that appears 5959_before_ your bug example, if you think it might affect our ability to 5960reproduce it. 5961 5962 Please try to produce the problem in an Emacs instance without any 5963customizations loaded (i.e., start it with the ‘-q --no-site-file’ 5964arguments). If it works correctly there, the problem might be caused by 5965faulty customizations in either your own or your site configuration. In 5966that case, we’d appreciate it if you isolate the Emacs Lisp code that 5967triggers the bug and include it in your report. 5968 5969 Reporting a bug using ‘c-submit-bug-report’ files it in the GNU Bug 5970Tracker at <https://debbugs.gnu.org>, then sends it on to 5971<bug-cc-mode@gnu.org>. You can also send reports, other questions, and 5972suggestions (kudos? ;-) to that address. It’s a mailing list which you 5973can join or browse an archive of; see the web site at 5974<http://cc-mode.sourceforge.net/> for further details. 5975 5976 If you want to get announcements of new CC Mode releases, send the 5977word _subscribe_ in the body of a message to 5978<cc-mode-announce-request@lists.sourceforge.net>. It’s possible to 5979subscribe from the web site too. Announcements will also be posted to 5980the Usenet newsgroups ‘gnu.emacs.sources’, ‘comp.emacs’, 5981‘comp.emacs.xemacs’, ‘comp.lang.c’, ‘comp.lang.c++’, 5982‘comp.lang.objective-c’, ‘comp.lang.java.softwaretools’, 5983‘comp.lang.idl’, and ‘comp.lang.awk’. 5984 5985 5986File: ccmode.info, Node: GNU Free Documentation License, Next: Command and Function Index, Prev: Mailing Lists and Bug Reports, Up: Top 5987 5988Appendix G GNU Free Documentation License 5989***************************************** 5990 5991 Version 1.3, 3 November 2008 5992 5993 Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 5994 <https://fsf.org/> 5995 5996 Everyone is permitted to copy and distribute verbatim copies 5997 of this license document, but changing it is not allowed. 5998 5999 0. PREAMBLE 6000 6001 The purpose of this License is to make a manual, textbook, or other 6002 functional and useful document “free” in the sense of freedom: to 6003 assure everyone the effective freedom to copy and redistribute it, 6004 with or without modifying it, either commercially or 6005 noncommercially. Secondarily, this License preserves for the 6006 author and publisher a way to get credit for their work, while not 6007 being considered responsible for modifications made by others. 6008 6009 This License is a kind of “copyleft”, which means that derivative 6010 works of the document must themselves be free in the same sense. 6011 It complements the GNU General Public License, which is a copyleft 6012 license designed for free software. 6013 6014 We have designed this License in order to use it for manuals for 6015 free software, because free software needs free documentation: a 6016 free program should come with manuals providing the same freedoms 6017 that the software does. But this License is not limited to 6018 software manuals; it can be used for any textual work, regardless 6019 of subject matter or whether it is published as a printed book. We 6020 recommend this License principally for works whose purpose is 6021 instruction or reference. 6022 6023 1. APPLICABILITY AND DEFINITIONS 6024 6025 This License applies to any manual or other work, in any medium, 6026 that contains a notice placed by the copyright holder saying it can 6027 be distributed under the terms of this License. Such a notice 6028 grants a world-wide, royalty-free license, unlimited in duration, 6029 to use that work under the conditions stated herein. The 6030 “Document”, below, refers to any such manual or work. Any member 6031 of the public is a licensee, and is addressed as “you”. You accept 6032 the license if you copy, modify or distribute the work in a way 6033 requiring permission under copyright law. 6034 6035 A “Modified Version” of the Document means any work containing the 6036 Document or a portion of it, either copied verbatim, or with 6037 modifications and/or translated into another language. 6038 6039 A “Secondary Section” is a named appendix or a front-matter section 6040 of the Document that deals exclusively with the relationship of the 6041 publishers or authors of the Document to the Document’s overall 6042 subject (or to related matters) and contains nothing that could 6043 fall directly within that overall subject. (Thus, if the Document 6044 is in part a textbook of mathematics, a Secondary Section may not 6045 explain any mathematics.) The relationship could be a matter of 6046 historical connection with the subject or with related matters, or 6047 of legal, commercial, philosophical, ethical or political position 6048 regarding them. 6049 6050 The “Invariant Sections” are certain Secondary Sections whose 6051 titles are designated, as being those of Invariant Sections, in the 6052 notice that says that the Document is released under this License. 6053 If a section does not fit the above definition of Secondary then it 6054 is not allowed to be designated as Invariant. The Document may 6055 contain zero Invariant Sections. If the Document does not identify 6056 any Invariant Sections then there are none. 6057 6058 The “Cover Texts” are certain short passages of text that are 6059 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 6060 that says that the Document is released under this License. A 6061 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 6062 be at most 25 words. 6063 6064 A “Transparent” copy of the Document means a machine-readable copy, 6065 represented in a format whose specification is available to the 6066 general public, that is suitable for revising the document 6067 straightforwardly with generic text editors or (for images composed 6068 of pixels) generic paint programs or (for drawings) some widely 6069 available drawing editor, and that is suitable for input to text 6070 formatters or for automatic translation to a variety of formats 6071 suitable for input to text formatters. A copy made in an otherwise 6072 Transparent file format whose markup, or absence of markup, has 6073 been arranged to thwart or discourage subsequent modification by 6074 readers is not Transparent. An image format is not Transparent if 6075 used for any substantial amount of text. A copy that is not 6076 “Transparent” is called “Opaque”. 6077 6078 Examples of suitable formats for Transparent copies include plain 6079 ASCII without markup, Texinfo input format, LaTeX input format, 6080 SGML or XML using a publicly available DTD, and standard-conforming 6081 simple HTML, PostScript or PDF designed for human modification. 6082 Examples of transparent image formats include PNG, XCF and JPG. 6083 Opaque formats include proprietary formats that can be read and 6084 edited only by proprietary word processors, SGML or XML for which 6085 the DTD and/or processing tools are not generally available, and 6086 the machine-generated HTML, PostScript or PDF produced by some word 6087 processors for output purposes only. 6088 6089 The “Title Page” means, for a printed book, the title page itself, 6090 plus such following pages as are needed to hold, legibly, the 6091 material this License requires to appear in the title page. For 6092 works in formats which do not have any title page as such, “Title 6093 Page” means the text near the most prominent appearance of the 6094 work’s title, preceding the beginning of the body of the text. 6095 6096 The “publisher” means any person or entity that distributes copies 6097 of the Document to the public. 6098 6099 A section “Entitled XYZ” means a named subunit of the Document 6100 whose title either is precisely XYZ or contains XYZ in parentheses 6101 following text that translates XYZ in another language. (Here XYZ 6102 stands for a specific section name mentioned below, such as 6103 “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) 6104 To “Preserve the Title” of such a section when you modify the 6105 Document means that it remains a section “Entitled XYZ” according 6106 to this definition. 6107 6108 The Document may include Warranty Disclaimers next to the notice 6109 which states that this License applies to the Document. These 6110 Warranty Disclaimers are considered to be included by reference in 6111 this License, but only as regards disclaiming warranties: any other 6112 implication that these Warranty Disclaimers may have is void and 6113 has no effect on the meaning of this License. 6114 6115 2. VERBATIM COPYING 6116 6117 You may copy and distribute the Document in any medium, either 6118 commercially or noncommercially, provided that this License, the 6119 copyright notices, and the license notice saying this License 6120 applies to the Document are reproduced in all copies, and that you 6121 add no other conditions whatsoever to those of this License. You 6122 may not use technical measures to obstruct or control the reading 6123 or further copying of the copies you make or distribute. However, 6124 you may accept compensation in exchange for copies. If you 6125 distribute a large enough number of copies you must also follow the 6126 conditions in section 3. 6127 6128 You may also lend copies, under the same conditions stated above, 6129 and you may publicly display copies. 6130 6131 3. COPYING IN QUANTITY 6132 6133 If you publish printed copies (or copies in media that commonly 6134 have printed covers) of the Document, numbering more than 100, and 6135 the Document’s license notice requires Cover Texts, you must 6136 enclose the copies in covers that carry, clearly and legibly, all 6137 these Cover Texts: Front-Cover Texts on the front cover, and 6138 Back-Cover Texts on the back cover. Both covers must also clearly 6139 and legibly identify you as the publisher of these copies. The 6140 front cover must present the full title with all words of the title 6141 equally prominent and visible. You may add other material on the 6142 covers in addition. Copying with changes limited to the covers, as 6143 long as they preserve the title of the Document and satisfy these 6144 conditions, can be treated as verbatim copying in other respects. 6145 6146 If the required texts for either cover are too voluminous to fit 6147 legibly, you should put the first ones listed (as many as fit 6148 reasonably) on the actual cover, and continue the rest onto 6149 adjacent pages. 6150 6151 If you publish or distribute Opaque copies of the Document 6152 numbering more than 100, you must either include a machine-readable 6153 Transparent copy along with each Opaque copy, or state in or with 6154 each Opaque copy a computer-network location from which the general 6155 network-using public has access to download using public-standard 6156 network protocols a complete Transparent copy of the Document, free 6157 of added material. If you use the latter option, you must take 6158 reasonably prudent steps, when you begin distribution of Opaque 6159 copies in quantity, to ensure that this Transparent copy will 6160 remain thus accessible at the stated location until at least one 6161 year after the last time you distribute an Opaque copy (directly or 6162 through your agents or retailers) of that edition to the public. 6163 6164 It is requested, but not required, that you contact the authors of 6165 the Document well before redistributing any large number of copies, 6166 to give them a chance to provide you with an updated version of the 6167 Document. 6168 6169 4. MODIFICATIONS 6170 6171 You may copy and distribute a Modified Version of the Document 6172 under the conditions of sections 2 and 3 above, provided that you 6173 release the Modified Version under precisely this License, with the 6174 Modified Version filling the role of the Document, thus licensing 6175 distribution and modification of the Modified Version to whoever 6176 possesses a copy of it. In addition, you must do these things in 6177 the Modified Version: 6178 6179 A. Use in the Title Page (and on the covers, if any) a title 6180 distinct from that of the Document, and from those of previous 6181 versions (which should, if there were any, be listed in the 6182 History section of the Document). You may use the same title 6183 as a previous version if the original publisher of that 6184 version gives permission. 6185 6186 B. List on the Title Page, as authors, one or more persons or 6187 entities responsible for authorship of the modifications in 6188 the Modified Version, together with at least five of the 6189 principal authors of the Document (all of its principal 6190 authors, if it has fewer than five), unless they release you 6191 from this requirement. 6192 6193 C. State on the Title page the name of the publisher of the 6194 Modified Version, as the publisher. 6195 6196 D. Preserve all the copyright notices of the Document. 6197 6198 E. Add an appropriate copyright notice for your modifications 6199 adjacent to the other copyright notices. 6200 6201 F. Include, immediately after the copyright notices, a license 6202 notice giving the public permission to use the Modified 6203 Version under the terms of this License, in the form shown in 6204 the Addendum below. 6205 6206 G. Preserve in that license notice the full lists of Invariant 6207 Sections and required Cover Texts given in the Document’s 6208 license notice. 6209 6210 H. Include an unaltered copy of this License. 6211 6212 I. Preserve the section Entitled “History”, Preserve its Title, 6213 and add to it an item stating at least the title, year, new 6214 authors, and publisher of the Modified Version as given on the 6215 Title Page. If there is no section Entitled “History” in the 6216 Document, create one stating the title, year, authors, and 6217 publisher of the Document as given on its Title Page, then add 6218 an item describing the Modified Version as stated in the 6219 previous sentence. 6220 6221 J. Preserve the network location, if any, given in the Document 6222 for public access to a Transparent copy of the Document, and 6223 likewise the network locations given in the Document for 6224 previous versions it was based on. These may be placed in the 6225 “History” section. You may omit a network location for a work 6226 that was published at least four years before the Document 6227 itself, or if the original publisher of the version it refers 6228 to gives permission. 6229 6230 K. For any section Entitled “Acknowledgements” or “Dedications”, 6231 Preserve the Title of the section, and preserve in the section 6232 all the substance and tone of each of the contributor 6233 acknowledgements and/or dedications given therein. 6234 6235 L. Preserve all the Invariant Sections of the Document, unaltered 6236 in their text and in their titles. Section numbers or the 6237 equivalent are not considered part of the section titles. 6238 6239 M. Delete any section Entitled “Endorsements”. Such a section 6240 may not be included in the Modified Version. 6241 6242 N. Do not retitle any existing section to be Entitled 6243 “Endorsements” or to conflict in title with any Invariant 6244 Section. 6245 6246 O. Preserve any Warranty Disclaimers. 6247 6248 If the Modified Version includes new front-matter sections or 6249 appendices that qualify as Secondary Sections and contain no 6250 material copied from the Document, you may at your option designate 6251 some or all of these sections as invariant. To do this, add their 6252 titles to the list of Invariant Sections in the Modified Version’s 6253 license notice. These titles must be distinct from any other 6254 section titles. 6255 6256 You may add a section Entitled “Endorsements”, provided it contains 6257 nothing but endorsements of your Modified Version by various 6258 parties—for example, statements of peer review or that the text has 6259 been approved by an organization as the authoritative definition of 6260 a standard. 6261 6262 You may add a passage of up to five words as a Front-Cover Text, 6263 and a passage of up to 25 words as a Back-Cover Text, to the end of 6264 the list of Cover Texts in the Modified Version. Only one passage 6265 of Front-Cover Text and one of Back-Cover Text may be added by (or 6266 through arrangements made by) any one entity. If the Document 6267 already includes a cover text for the same cover, previously added 6268 by you or by arrangement made by the same entity you are acting on 6269 behalf of, you may not add another; but you may replace the old 6270 one, on explicit permission from the previous publisher that added 6271 the old one. 6272 6273 The author(s) and publisher(s) of the Document do not by this 6274 License give permission to use their names for publicity for or to 6275 assert or imply endorsement of any Modified Version. 6276 6277 5. COMBINING DOCUMENTS 6278 6279 You may combine the Document with other documents released under 6280 this License, under the terms defined in section 4 above for 6281 modified versions, provided that you include in the combination all 6282 of the Invariant Sections of all of the original documents, 6283 unmodified, and list them all as Invariant Sections of your 6284 combined work in its license notice, and that you preserve all 6285 their Warranty Disclaimers. 6286 6287 The combined work need only contain one copy of this License, and 6288 multiple identical Invariant Sections may be replaced with a single 6289 copy. If there are multiple Invariant Sections with the same name 6290 but different contents, make the title of each such section unique 6291 by adding at the end of it, in parentheses, the name of the 6292 original author or publisher of that section if known, or else a 6293 unique number. Make the same adjustment to the section titles in 6294 the list of Invariant Sections in the license notice of the 6295 combined work. 6296 6297 In the combination, you must combine any sections Entitled 6298 “History” in the various original documents, forming one section 6299 Entitled “History”; likewise combine any sections Entitled 6300 “Acknowledgements”, and any sections Entitled “Dedications”. You 6301 must delete all sections Entitled “Endorsements.” 6302 6303 6. COLLECTIONS OF DOCUMENTS 6304 6305 You may make a collection consisting of the Document and other 6306 documents released under this License, and replace the individual 6307 copies of this License in the various documents with a single copy 6308 that is included in the collection, provided that you follow the 6309 rules of this License for verbatim copying of each of the documents 6310 in all other respects. 6311 6312 You may extract a single document from such a collection, and 6313 distribute it individually under this License, provided you insert 6314 a copy of this License into the extracted document, and follow this 6315 License in all other respects regarding verbatim copying of that 6316 document. 6317 6318 7. AGGREGATION WITH INDEPENDENT WORKS 6319 6320 A compilation of the Document or its derivatives with other 6321 separate and independent documents or works, in or on a volume of a 6322 storage or distribution medium, is called an “aggregate” if the 6323 copyright resulting from the compilation is not used to limit the 6324 legal rights of the compilation’s users beyond what the individual 6325 works permit. When the Document is included in an aggregate, this 6326 License does not apply to the other works in the aggregate which 6327 are not themselves derivative works of the Document. 6328 6329 If the Cover Text requirement of section 3 is applicable to these 6330 copies of the Document, then if the Document is less than one half 6331 of the entire aggregate, the Document’s Cover Texts may be placed 6332 on covers that bracket the Document within the aggregate, or the 6333 electronic equivalent of covers if the Document is in electronic 6334 form. Otherwise they must appear on printed covers that bracket 6335 the whole aggregate. 6336 6337 8. TRANSLATION 6338 6339 Translation is considered a kind of modification, so you may 6340 distribute translations of the Document under the terms of section 6341 4. Replacing Invariant Sections with translations requires special 6342 permission from their copyright holders, but you may include 6343 translations of some or all Invariant Sections in addition to the 6344 original versions of these Invariant Sections. You may include a 6345 translation of this License, and all the license notices in the 6346 Document, and any Warranty Disclaimers, provided that you also 6347 include the original English version of this License and the 6348 original versions of those notices and disclaimers. In case of a 6349 disagreement between the translation and the original version of 6350 this License or a notice or disclaimer, the original version will 6351 prevail. 6352 6353 If a section in the Document is Entitled “Acknowledgements”, 6354 “Dedications”, or “History”, the requirement (section 4) to 6355 Preserve its Title (section 1) will typically require changing the 6356 actual title. 6357 6358 9. TERMINATION 6359 6360 You may not copy, modify, sublicense, or distribute the Document 6361 except as expressly provided under this License. Any attempt 6362 otherwise to copy, modify, sublicense, or distribute it is void, 6363 and will automatically terminate your rights under this License. 6364 6365 However, if you cease all violation of this License, then your 6366 license from a particular copyright holder is reinstated (a) 6367 provisionally, unless and until the copyright holder explicitly and 6368 finally terminates your license, and (b) permanently, if the 6369 copyright holder fails to notify you of the violation by some 6370 reasonable means prior to 60 days after the cessation. 6371 6372 Moreover, your license from a particular copyright holder is 6373 reinstated permanently if the copyright holder notifies you of the 6374 violation by some reasonable means, this is the first time you have 6375 received notice of violation of this License (for any work) from 6376 that copyright holder, and you cure the violation prior to 30 days 6377 after your receipt of the notice. 6378 6379 Termination of your rights under this section does not terminate 6380 the licenses of parties who have received copies or rights from you 6381 under this License. If your rights have been terminated and not 6382 permanently reinstated, receipt of a copy of some or all of the 6383 same material does not give you any rights to use it. 6384 6385 10. FUTURE REVISIONS OF THIS LICENSE 6386 6387 The Free Software Foundation may publish new, revised versions of 6388 the GNU Free Documentation License from time to time. Such new 6389 versions will be similar in spirit to the present version, but may 6390 differ in detail to address new problems or concerns. See 6391 <https://www.gnu.org/licenses/>. 6392 6393 Each version of the License is given a distinguishing version 6394 number. If the Document specifies that a particular numbered 6395 version of this License “or any later version” applies to it, you 6396 have the option of following the terms and conditions either of 6397 that specified version or of any later version that has been 6398 published (not as a draft) by the Free Software Foundation. If the 6399 Document does not specify a version number of this License, you may 6400 choose any version ever published (not as a draft) by the Free 6401 Software Foundation. If the Document specifies that a proxy can 6402 decide which future versions of this License can be used, that 6403 proxy’s public statement of acceptance of a version permanently 6404 authorizes you to choose that version for the Document. 6405 6406 11. RELICENSING 6407 6408 “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any 6409 World Wide Web server that publishes copyrightable works and also 6410 provides prominent facilities for anybody to edit those works. A 6411 public wiki that anybody can edit is an example of such a server. 6412 A “Massive Multiauthor Collaboration” (or “MMC”) contained in the 6413 site means any set of copyrightable works thus published on the MMC 6414 site. 6415 6416 “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 6417 license published by Creative Commons Corporation, a not-for-profit 6418 corporation with a principal place of business in San Francisco, 6419 California, as well as future copyleft versions of that license 6420 published by that same organization. 6421 6422 “Incorporate” means to publish or republish a Document, in whole or 6423 in part, as part of another Document. 6424 6425 An MMC is “eligible for relicensing” if it is licensed under this 6426 License, and if all works that were first published under this 6427 License somewhere other than this MMC, and subsequently 6428 incorporated in whole or in part into the MMC, (1) had no cover 6429 texts or invariant sections, and (2) were thus incorporated prior 6430 to November 1, 2008. 6431 6432 The operator of an MMC Site may republish an MMC contained in the 6433 site under CC-BY-SA on the same site at any time before August 1, 6434 2009, provided the MMC is eligible for relicensing. 6435 6436ADDENDUM: How to use this License for your documents 6437==================================================== 6438 6439To use this License in a document you have written, include a copy of 6440the License in the document and put the following copyright and license 6441notices just after the title page: 6442 6443 Copyright (C) YEAR YOUR NAME. 6444 Permission is granted to copy, distribute and/or modify this document 6445 under the terms of the GNU Free Documentation License, Version 1.3 6446 or any later version published by the Free Software Foundation; 6447 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 6448 Texts. A copy of the license is included in the section entitled ``GNU 6449 Free Documentation License''. 6450 6451 If you have Invariant Sections, Front-Cover Texts and Back-Cover 6452Texts, replace the “with...Texts.” line with this: 6453 6454 with the Invariant Sections being LIST THEIR TITLES, with 6455 the Front-Cover Texts being LIST, and with the Back-Cover Texts 6456 being LIST. 6457 6458 If you have Invariant Sections without Cover Texts, or some other 6459combination of the three, merge those two alternatives to suit the 6460situation. 6461 6462 If your document contains nontrivial examples of program code, we 6463recommend releasing these examples in parallel under your choice of free 6464software license, such as the GNU General Public License, to permit 6465their use in free software. 6466 6467 6468File: ccmode.info, Node: Command and Function Index, Next: Variable Index, Prev: GNU Free Documentation License, Up: Top 6469 6470Command and Function Index 6471************************** 6472 6473Since most CC Mode commands are prepended with the string ‘c-’, each 6474appears under its ‘c-THING’ name and its ‘THING (c-)’ name. 6475 6476�[index�] 6477* Menu: 6478 6479* abbrev-mode: Electric Keys. (line 124) 6480* add-style (c-): Adding Styles. (line 53) 6481* auto-fill-mode: Filling and Breaking. 6482 (line 19) 6483* awk-beginning-of-defun (c-): Movement Commands. (line 38) 6484* awk-end-of-defun (c-): Movement Commands. (line 38) 6485* awk-mode: Introduction. (line 28) 6486* backslash-region (c-): Other Commands. (line 40) 6487* backward-conditional (c-): Movement Commands. (line 96) 6488* backward-delete-char-untabify: Hungry WS Deletion. (line 40) 6489* backward-into-nomenclature (c-): Movement Commands. (line 105) 6490* backward-kill-subword (c-): Subword Movement. (line 23) 6491* backward-subword (c-): Subword Movement. (line 23) 6492* beginning-of-defun: Performance Issues. (line 31) 6493* beginning-of-statement (c-): Movement Commands. (line 49) 6494* c++-mode: Introduction. (line 28) 6495* c-add-style: Adding Styles. (line 52) 6496* c-awk-beginning-of-defun: Movement Commands. (line 38) 6497* c-awk-end-of-defun: Movement Commands. (line 38) 6498* c-backslash-region: Other Commands. (line 40) 6499* c-backward-conditional: Movement Commands. (line 96) 6500* c-backward-into-nomenclature: Movement Commands. (line 105) 6501* c-backward-kill-subword: Subword Movement. (line 23) 6502* c-backward-subword: Subword Movement. (line 23) 6503* c-beginning-of-defun: Movement Commands. (line 10) 6504* c-beginning-of-statement: Movement Commands. (line 49) 6505* c-capitalize-subword: Subword Movement. (line 23) 6506* c-context-line-break: Filling and Breaking. 6507 (line 48) 6508* c-context-open-line: Filling and Breaking. 6509 (line 64) 6510* c-display-defun-name: Other Commands. (line 31) 6511* c-down-conditional: Movement Commands. (line 82) 6512* c-down-conditional-with-else: Movement Commands. (line 91) 6513* c-downcase-subword: Subword Movement. (line 23) 6514* c-electric-backspace: Hungry WS Deletion. (line 30) 6515* c-electric-brace: Electric Keys. (line 76) 6516* c-electric-colon: Electric Keys. (line 83) 6517* c-electric-continued-statement: Electric Keys. (line 103) 6518* c-electric-delete: Hungry WS Deletion. (line 83) 6519* c-electric-delete-forward: Hungry WS Deletion. (line 47) 6520* c-electric-lt-gt: Electric Keys. (line 54) 6521* c-electric-paren: Electric Keys. (line 63) 6522* c-electric-pound: Electric Keys. (line 24) 6523* c-electric-semi&comma: Electric Keys. (line 96) 6524* c-electric-slash: Electric Keys. (line 38) 6525* c-electric-star: Electric Keys. (line 38) 6526* c-end-of-defun: Movement Commands. (line 10) 6527* c-end-of-statement: Movement Commands. (line 49) 6528* c-fill-paragraph: Filling and Breaking. 6529 (line 26) 6530* c-forward-conditional: Movement Commands. (line 96) 6531* c-forward-into-nomenclature: Movement Commands. (line 105) 6532* c-forward-subword: Subword Movement. (line 23) 6533* c-gnu-impose-minimum: Other Indentation. (line 16) 6534* c-guess: Guessing the Style. (line 41) 6535* c-guess-basic-syntax: Syntactic Analysis. (line 13) 6536* c-guess-buffer: Guessing the Style. (line 41) 6537* c-guess-buffer-no-install: Guessing the Style. (line 26) 6538* c-guess-install: Guessing the Style. (line 67) 6539* c-guess-no-install: Guessing the Style. (line 26) 6540* c-guess-region: Guessing the Style. (line 41) 6541* c-guess-region-no-install: Guessing the Style. (line 26) 6542* c-guess-view: Guessing the Style. (line 74) 6543* c-hungry-delete: Hungry WS Deletion. (line 83) 6544* c-hungry-delete-backwards: Hungry WS Deletion. (line 66) 6545* c-hungry-delete-forward: Hungry WS Deletion. (line 73) 6546* c-indent-command: Indentation Commands. 6547 (line 42) 6548* c-indent-defun: Indentation Commands. 6549 (line 102) 6550* c-indent-exp: Indentation Commands. 6551 (line 97) 6552* c-indent-multi-line-block: Brace/Paren Line-Up. (line 68) 6553* c-indent-new-comment-line: Filling and Breaking. 6554 (line 41) 6555* c-indent-one-line-block: Brace/Paren Line-Up. (line 47) 6556* c-kill-subword: Subword Movement. (line 23) 6557* c-langelem-2nd-pos: Custom Line-Up. (line 73) 6558* c-langelem-col: Custom Line-Up. (line 69) 6559* c-langelem-pos: Custom Line-Up. (line 66) 6560* c-langelem-sym: Custom Line-Up. (line 63) 6561* c-lineup-2nd-brace-entry-in-arglist: List Line-Up. (line 40) 6562* c-lineup-after-whitesmith-blocks: Brace/Paren Line-Up. (line 117) 6563* c-lineup-argcont: Operator Line-Up. (line 10) 6564* c-lineup-arglist: List Line-Up. (line 13) 6565* c-lineup-arglist-close-under-paren: Brace/Paren Line-Up. (line 31) 6566* c-lineup-arglist-intro-after-paren: List Line-Up. (line 33) 6567* c-lineup-arglist-operators: Operator Line-Up. (line 25) 6568* c-lineup-assignments: Operator Line-Up. (line 49) 6569* c-lineup-C-comments: Comment Line-Up. (line 9) 6570* c-lineup-cascaded-calls: Operator Line-Up. (line 68) 6571* c-lineup-class-decl-init-+: List Line-Up. (line 65) 6572* c-lineup-class-decl-init-after-brace: List Line-Up. (line 94) 6573* c-lineup-close-paren: Brace/Paren Line-Up. (line 9) 6574* c-lineup-comment: Comment Line-Up. (line 40) 6575* c-lineup-cpp-define: Misc Line-Up. (line 23) 6576* c-lineup-dont-change: Misc Line-Up. (line 9) 6577* c-lineup-gcc-asm-reg: Misc Line-Up. (line 89) 6578* c-lineup-inexpr-block: Brace/Paren Line-Up. (line 107) 6579* c-lineup-java-inher: List Line-Up. (line 146) 6580* c-lineup-java-throws: List Line-Up. (line 165) 6581* c-lineup-knr-region-comment: Comment Line-Up. (line 58) 6582* c-lineup-math: Operator Line-Up. (line 59) 6583* c-lineup-multi-inher: List Line-Up. (line 124) 6584* c-lineup-ObjC-method-args: List Line-Up. (line 206) 6585* c-lineup-ObjC-method-args-2: List Line-Up. (line 213) 6586* c-lineup-ObjC-method-call: List Line-Up. (line 196) 6587* c-lineup-runin-statements: Brace/Paren Line-Up. (line 91) 6588* c-lineup-streamop: Operator Line-Up. (line 84) 6589* c-lineup-string-cont: Operator Line-Up. (line 89) 6590* c-lineup-template-args: List Line-Up. (line 186) 6591* c-lineup-topmost-intro-cont: Misc Line-Up. (line 111) 6592* c-lineup-under-anchor: Misc Line-Up. (line 15) 6593* c-lineup-whitesmith-in-block: Brace/Paren Line-Up. (line 150) 6594* c-macro-expand: Other Commands. (line 65) 6595* c-make-macro-with-semi-re: Macros with ;. (line 42) 6596* c-make-noise-macro-regexps: Noise Macros. (line 40) 6597* c-mark-function: Indentation Commands. 6598 (line 115) 6599* c-mark-subword: Subword Movement. (line 23) 6600* c-mode: Introduction. (line 28) 6601* c-scope-operator: Other Commands. (line 26) 6602* c-semi&comma-inside-parenlist: Hanging Semicolons and Commas. 6603 (line 53) 6604* c-semi&comma-no-newlines-before-nonblanks: Hanging Semicolons and Commas. 6605 (line 37) 6606* c-semi&comma-no-newlines-for-oneline-inliners: Hanging Semicolons and Commas. 6607 (line 54) 6608* c-set-offset: c-offsets-alist. (line 41) 6609* c-set-offset <1>: Interactive Customization. 6610 (line 71) 6611* c-set-style: Other Commands. (line 9) 6612* c-setup-doc-comment-style: Doc Comments. (line 35) 6613* c-setup-filladapt: Custom Filling and Breaking. 6614 (line 72) 6615* c-setup-paragraph-variables: Custom Filling and Breaking. 6616 (line 46) 6617* c-show-syntactic-information: Syntactic Analysis. (line 50) 6618* c-snug-do-while: Custom Braces. (line 67) 6619* c-submit-bug-report: Mailing Lists and Bug Reports. 6620 (line 6) 6621* c-toggle-auto-hungry-state: Minor Modes. (line 76) 6622* c-toggle-auto-newline: Minor Modes. (line 69) 6623* c-toggle-comment-style: Minor Modes. (line 60) 6624* c-toggle-electric-state: Minor Modes. (line 65) 6625* c-toggle-hungry-state: Minor Modes. (line 73) 6626* c-toggle-syntactic-indentation: Minor Modes. (line 82) 6627* c-transpose-subwords: Subword Movement. (line 23) 6628* c-up-conditional: Movement Commands. (line 66) 6629* c-up-conditional-with-else: Movement Commands. (line 78) 6630* c-upcase-subword: Subword Movement. (line 23) 6631* c-version: Getting Started. (line 82) 6632* capitalize-subword (c-): Subword Movement. (line 23) 6633* comment-dwim: Comment Commands. (line 18) 6634* comment-region: Comment Commands. (line 11) 6635* context-line-break (c-): Filling and Breaking. 6636 (line 48) 6637* context-open-line (c-): Filling and Breaking. 6638 (line 64) 6639* defun-prompt-regexp: Performance Issues. (line 39) 6640* delete-char: Hungry WS Deletion. (line 55) 6641* display-defun-name (c-): Other Commands. (line 31) 6642* down-conditional (c-): Movement Commands. (line 82) 6643* down-conditional-with-else (c-): Movement Commands. (line 91) 6644* downcase-subword (c-): Subword Movement. (line 23) 6645* electric-backspace (c-): Hungry WS Deletion. (line 30) 6646* electric-brace (c-): Electric Keys. (line 76) 6647* electric-colon (c-): Electric Keys. (line 83) 6648* electric-continued-statement (c-): Electric Keys. (line 104) 6649* electric-delete (c-): Hungry WS Deletion. (line 83) 6650* electric-delete-forward (c-): Hungry WS Deletion. (line 47) 6651* electric-lt-gt (c-): Electric Keys. (line 54) 6652* electric-paren (c-): Electric Keys. (line 63) 6653* electric-pound (c-): Electric Keys. (line 24) 6654* electric-semi&comma (c-): Electric Keys. (line 96) 6655* electric-slash (c-): Electric Keys. (line 38) 6656* electric-star (c-): Electric Keys. (line 38) 6657* end-of-statement (c-): Movement Commands. (line 49) 6658* fill-paragraph (c-): Filling and Breaking. 6659 (line 26) 6660* filladapt-mode: Custom Filling and Breaking. 6661 (line 72) 6662* forward-conditional (c-): Movement Commands. (line 96) 6663* forward-into-nomenclature (c-): Movement Commands. (line 105) 6664* forward-subword (c-): Subword Movement. (line 23) 6665* gnu-impose-minimum (c-): Other Indentation. (line 16) 6666* guess (c-): Guessing the Style. (line 41) 6667* guess-basic-syntax (c-): Syntactic Analysis. (line 14) 6668* guess-buffer (c-): Guessing the Style. (line 41) 6669* guess-buffer-no-install (c-): Guessing the Style. (line 26) 6670* guess-install (c-): Guessing the Style. (line 67) 6671* guess-no-install (c-): Guessing the Style. (line 26) 6672* guess-region (c-): Guessing the Style. (line 41) 6673* guess-region-no-install (c-): Guessing the Style. (line 26) 6674* guess-view (c-): Guessing the Style. (line 74) 6675* hungry-delete (c-): Hungry WS Deletion. (line 83) 6676* hungry-delete-backwards (c-): Hungry WS Deletion. (line 66) 6677* hungry-delete-forward (c-): Hungry WS Deletion. (line 73) 6678* idl-mode: Introduction. (line 28) 6679* indent-command (c-): Indentation Commands. 6680 (line 42) 6681* indent-defun (c-): Indentation Commands. 6682 (line 102) 6683* indent-exp (c-): Indentation Commands. 6684 (line 97) 6685* indent-for-comment: Comment Commands. (line 18) 6686* indent-multi-line-block (c-): Brace/Paren Line-Up. (line 69) 6687* indent-new-comment-line (c-): Filling and Breaking. 6688 (line 41) 6689* indent-one-line-block (c-): Brace/Paren Line-Up. (line 48) 6690* indent-region: Indentation Commands. 6691 (line 110) 6692* java-mode: Introduction. (line 28) 6693* kill-subword (c-): Subword Movement. (line 23) 6694* langelem-2nd-pos (c-): Custom Line-Up. (line 74) 6695* langelem-col (c-): Custom Line-Up. (line 70) 6696* langelem-pos (c-): Custom Line-Up. (line 67) 6697* langelem-sym (c-): Custom Line-Up. (line 64) 6698* lineup-2nd-brace-entry-in-arglist (c-): List Line-Up. (line 41) 6699* lineup-after-whitesmith-blocks (c-): Brace/Paren Line-Up. (line 118) 6700* lineup-argcont (c-): Operator Line-Up. (line 11) 6701* lineup-arglist (c-): List Line-Up. (line 14) 6702* lineup-arglist-close-under-paren (c-): Brace/Paren Line-Up. (line 32) 6703* lineup-arglist-intro-after-paren (c-): List Line-Up. (line 34) 6704* lineup-arglist-operators (c-): Operator Line-Up. (line 26) 6705* lineup-assignments (c-): Operator Line-Up. (line 50) 6706* lineup-C-comments (c-): Comment Line-Up. (line 10) 6707* lineup-cascaded-calls (c-): Operator Line-Up. (line 69) 6708* lineup-class-decl-init-+ (c-): List Line-Up. (line 66) 6709* lineup-class-decl-init-after-brace (c-): List Line-Up. (line 95) 6710* lineup-close-paren (c-): Brace/Paren Line-Up. (line 10) 6711* lineup-comment (c-): Comment Line-Up. (line 41) 6712* lineup-cpp-define (c-): Misc Line-Up. (line 24) 6713* lineup-dont-change (c-): Misc Line-Up. (line 10) 6714* lineup-gcc-asm-reg (c-): Misc Line-Up. (line 90) 6715* lineup-inexpr-block (c-): Brace/Paren Line-Up. (line 108) 6716* lineup-java-inher (c-): List Line-Up. (line 147) 6717* lineup-java-throws (c-): List Line-Up. (line 166) 6718* lineup-knr-region-comment (c-): Comment Line-Up. (line 59) 6719* lineup-math (c-): Operator Line-Up. (line 60) 6720* lineup-multi-inher (c-): List Line-Up. (line 125) 6721* lineup-ObjC-method-args (c-): List Line-Up. (line 207) 6722* lineup-ObjC-method-args-2 (c-): List Line-Up. (line 214) 6723* lineup-ObjC-method-call (c-): List Line-Up. (line 197) 6724* lineup-runin-statements (c-): Brace/Paren Line-Up. (line 92) 6725* lineup-streamop (c-): Operator Line-Up. (line 85) 6726* lineup-string-cont (c-): Operator Line-Up. (line 90) 6727* lineup-template-args (c-): List Line-Up. (line 187) 6728* lineup-topmost-intro-cont (c-): Misc Line-Up. (line 112) 6729* lineup-whitesmith-in-block (c-): Brace/Paren Line-Up. (line 151) 6730* macro-expand (c-): Other Commands. (line 65) 6731* make-macro-with-semi-re (c-): Macros with ;. (line 43) 6732* make-noise-macro-regexps (c-): Noise Macros. (line 41) 6733* mark-function (c-): Indentation Commands. 6734 (line 115) 6735* mark-subword (c-): Subword Movement. (line 23) 6736* normal-erase-is-backspace-mode: Hungry WS Deletion. (line 93) 6737* objc-mode: Introduction. (line 28) 6738* pike-mode: Introduction. (line 28) 6739* scope-operator (c-): Other Commands. (line 26) 6740* semi&comma-inside-parenlist (c-): Hanging Semicolons and Commas. 6741 (line 54) 6742* semi&comma-no-newlines-before-nonblanks (c-): Hanging Semicolons and Commas. 6743 (line 38) 6744* semi&comma-no-newlines-for-oneline-inliners (c-): Hanging Semicolons and Commas. 6745 (line 55) 6746* set-offset (c-): c-offsets-alist. (line 42) 6747* set-offset (c-) <1>: Interactive Customization. 6748 (line 72) 6749* set-style (c-): Other Commands. (line 9) 6750* setup-doc-comment-style (c-): Doc Comments. (line 35) 6751* setup-filladapt (c-): Custom Filling and Breaking. 6752 (line 72) 6753* setup-paragraph-variables (c-): Custom Filling and Breaking. 6754 (line 46) 6755* show-syntactic-information (c-): Syntactic Analysis. (line 50) 6756* snug-do-while (c-): Custom Braces. (line 67) 6757* submit-bug-report (c-): Mailing Lists and Bug Reports. 6758 (line 6) 6759* subword-mode: Minor Modes. (line 79) 6760* tab-to-tab-stop: Indentation Commands. 6761 (line 80) 6762* toggle-auto-hungry-state (c-): Minor Modes. (line 76) 6763* toggle-auto-newline (c-): Minor Modes. (line 69) 6764* toggle-comment-style (c-): Minor Modes. (line 60) 6765* toggle-electric-state (c-): Minor Modes. (line 65) 6766* toggle-hungry-state (c-): Minor Modes. (line 73) 6767* toggle-syntactic-indentation (c-): Minor Modes. (line 82) 6768* transpose-subwords (c-): Subword Movement. (line 23) 6769* up-conditional (c-): Movement Commands. (line 66) 6770* up-conditional-with-else (c-): Movement Commands. (line 78) 6771* upcase-subword (c-): Subword Movement. (line 23) 6772* version (c-): Getting Started. (line 83) 6773 6774 6775File: ccmode.info, Node: Variable Index, Next: Concept and Key Index, Prev: Command and Function Index, Up: Top 6776 6777Variable Index 6778************** 6779 6780Since most CC Mode variables are prepended with the string ‘c-’, each 6781appears under its ‘c-THING’ name and its ‘THING (c-)’ name. 6782 6783�[index�] 6784* Menu: 6785 6786* abbrev-mode: Electric Keys. (line 124) 6787* adaptive-fill-first-line-regexp: Custom Filling and Breaking. 6788 (line 11) 6789* adaptive-fill-mode: Custom Filling and Breaking. 6790 (line 11) 6791* adaptive-fill-mode <1>: Custom Filling and Breaking. 6792 (line 58) 6793* adaptive-fill-regexp: Custom Filling and Breaking. 6794 (line 11) 6795* asymmetry-fontification-flag (c-): Misc Font Locking. (line 24) 6796* auto-align-backslashes (c-): Macro Backslashes. (line 31) 6797* awk-mode-hook: CC Hooks. (line 37) 6798* backslash-column (c-): Macro Backslashes. (line 11) 6799* backslash-max-column (c-): Macro Backslashes. (line 12) 6800* backspace-function (c-): Hungry WS Deletion. (line 40) 6801* basic-offset (c-): Customizing Indentation. 6802 (line 18) 6803* block-comment-prefix (c-): Custom Filling and Breaking. 6804 (line 84) 6805* c++-font-lock-extra-types: Font Locking Preliminaries. 6806 (line 58) 6807* c++-mode-hook: CC Hooks. (line 32) 6808* c-asymmetry-fontification-flag: Misc Font Locking. (line 23) 6809* c-auto-align-backslashes: Macro Backslashes. (line 30) 6810* c-backslash-column: Macro Backslashes. (line 10) 6811* c-backslash-max-column: Macro Backslashes. (line 11) 6812* c-backspace-function: Hungry WS Deletion. (line 40) 6813* c-basic-offset: Customizing Indentation. 6814 (line 17) 6815* c-block-comment-prefix: Custom Filling and Breaking. 6816 (line 83) 6817* c-cleanup-list: Clean-ups. (line 25) 6818* c-comment-continuation-stars: Custom Filling and Breaking. 6819 (line 84) 6820* c-comment-only-line-offset: Comment Line-Up. (line 45) 6821* c-comment-prefix-regexp: Custom Filling and Breaking. 6822 (line 11) 6823* c-comment-prefix-regexp <1>: Custom Filling and Breaking. 6824 (line 16) 6825* c-default-style: Choosing a Style. (line 19) 6826* c-defun-tactic: Movement Commands. (line 10) 6827* c-delete-function: Hungry WS Deletion. (line 55) 6828* c-doc-comment-style: Doc Comments. (line 11) 6829* c-echo-syntactic-information-p: Odds and Ends. (line 20) 6830* c-electric-pound-behavior: Electric Keys. (line 24) 6831* c-enable-xemacs-performance-kludge-p: Performance Issues. (line 62) 6832* c-file-offsets: File Styles. (line 21) 6833* c-file-style: File Styles. (line 16) 6834* c-font-lock-extra-types: Font Locking Preliminaries. 6835 (line 57) 6836* c-guess-offset-threshold: Guessing the Style. (line 60) 6837* c-guess-region-max: Guessing the Style. (line 55) 6838* c-hanging-braces-alist: Hanging Braces. (line 37) 6839* c-hanging-braces-alist <1>: Custom Braces. (line 6) 6840* c-hanging-colons-alist: Hanging Colons. (line 6) 6841* c-hanging-colons-alist <1>: Hanging Colons. (line 14) 6842* c-hanging-semi&comma-criteria: Hanging Semicolons and Commas. 6843 (line 6) 6844* c-ignore-auto-fill: Custom Filling and Breaking. 6845 (line 106) 6846* c-indent-comment-alist: Comment Commands. (line 26) 6847* c-indent-comments-syntactically-p: Comment Commands. (line 39) 6848* c-indentation-style: Choosing a Style. (line 44) 6849* c-initialization-hook: CC Hooks. (line 22) 6850* c-insert-tab-function: Indentation Commands. 6851 (line 79) 6852* c-invalid-face: Faces. (line 54) 6853* c-Java-defun-prompt-regexp: Performance Issues. (line 39) 6854* c-label-minimum-indentation: Other Indentation. (line 11) 6855* c-macro-names-with-semicolon: Macros with ;. (line 17) 6856* c-mark-wrong-style-of-comment: Wrong Comment Style. (line 15) 6857* c-max-one-liner-length: Clean-ups. (line 149) 6858* c-mode-common-hook: CC Hooks. (line 27) 6859* c-mode-hook: CC Hooks. (line 31) 6860* c-noise-macro-names: Noise Macros. (line 16) 6861* c-noise-macro-with-parens-names: Noise Macros. (line 24) 6862* c-offsets-alist: Syntactic Symbols. (line 6) 6863* c-offsets-alist <1>: c-offsets-alist. (line 11) 6864* c-old-style-variable-behavior: Style Variables. (line 19) 6865* c-progress-interval: Indentation Commands. 6866 (line 127) 6867* c-report-syntactic-errors: Odds and Ends. (line 27) 6868* c-require-final-newline: Odds and Ends. (line 8) 6869* c-special-indent-hook: Other Indentation. (line 20) 6870* c-strict-syntax-p: c-offsets-alist. (line 145) 6871* c-style-alist: Adding Styles. (line 68) 6872* c-syntactic-context: Custom Braces. (line 22) 6873* c-syntactic-context <1>: Custom Line-Up. (line 48) 6874* c-syntactic-element: Custom Line-Up. (line 48) 6875* c-syntactic-indentation: Indentation Engine Basics. 6876 (line 33) 6877* c-syntactic-indentation-in-macros: Custom Macros. (line 16) 6878* c-tab-always-indent: Indentation Commands. 6879 (line 66) 6880* cleanup-list (c-): Clean-ups. (line 26) 6881* comment-column: Comment Commands. (line 27) 6882* comment-continuation-stars (c-): Custom Filling and Breaking. 6883 (line 84) 6884* comment-end: Custom Filling and Breaking. 6885 (line 11) 6886* comment-multi-line: Custom Filling and Breaking. 6887 (line 135) 6888* comment-only-line-offset (c-): Comment Line-Up. (line 46) 6889* comment-prefix-regexp (c-): Custom Filling and Breaking. 6890 (line 11) 6891* comment-prefix-regexp (c-) <1>: Custom Filling and Breaking. 6892 (line 17) 6893* comment-start: Custom Filling and Breaking. 6894 (line 11) 6895* comment-start-skip: Custom Filling and Breaking. 6896 (line 11) 6897* comment-start-skip <1>: Comment Line-Up. (line 25) 6898* default-style (c-): Choosing a Style. (line 20) 6899* defun-tactic (c-): Movement Commands. (line 10) 6900* delete-function (c-): Hungry WS Deletion. (line 55) 6901* delete-key-deletes-forward: Hungry WS Deletion. (line 83) 6902* doc-comment-style (c-): Doc Comments. (line 12) 6903* echo-syntactic-information-p (c-): Odds and Ends. (line 21) 6904* electric-pound-behavior (c-): Electric Keys. (line 24) 6905* enable-xemacs-performance-kludge-p (c-): Performance Issues. 6906 (line 62) 6907* file-offsets (c-): File Styles. (line 22) 6908* file-style (c-): File Styles. (line 17) 6909* filladapt-mode: Custom Filling and Breaking. 6910 (line 72) 6911* font-lock-builtin-face: Faces. (line 50) 6912* font-lock-comment-face: Faces. (line 12) 6913* font-lock-comment-face <1>: Faces. (line 14) 6914* font-lock-constant-face: Faces. (line 32) 6915* font-lock-constant-face <1>: Faces. (line 41) 6916* font-lock-doc-face: Faces. (line 14) 6917* font-lock-doc-string-face: Faces. (line 14) 6918* font-lock-function-name-face: Faces. (line 24) 6919* font-lock-keyword-face: Faces. (line 22) 6920* font-lock-maximum-decoration: Font Locking Preliminaries. 6921 (line 25) 6922* font-lock-preprocessor-face: Faces. (line 50) 6923* font-lock-reference-face: Faces. (line 32) 6924* font-lock-reference-face <1>: Faces. (line 41) 6925* font-lock-reference-face <2>: Faces. (line 50) 6926* font-lock-string-face: Faces. (line 19) 6927* font-lock-type-face: Faces. (line 38) 6928* font-lock-variable-name-face: Faces. (line 28) 6929* font-lock-warning-face: Faces. (line 54) 6930* guess-offset-threshold (c-): Guessing the Style. (line 61) 6931* guess-region-max (c-): Guessing the Style. (line 56) 6932* hanging-braces-alist (c-): Hanging Braces. (line 38) 6933* hanging-braces-alist (c-) <1>: Custom Braces. (line 6) 6934* hanging-colons-alist (c-): Hanging Colons. (line 6) 6935* hanging-colons-alist (c-) <1>: Hanging Colons. (line 15) 6936* hanging-semi&comma-criteria (c-): Hanging Semicolons and Commas. 6937 (line 7) 6938* idl-font-lock-extra-types: Font Locking Preliminaries. 6939 (line 61) 6940* idl-mode-hook: CC Hooks. (line 35) 6941* ignore-auto-fill (c-): Custom Filling and Breaking. 6942 (line 107) 6943* indent-comment-alist (c-): Comment Commands. (line 27) 6944* indent-comments-syntactically-p (c-): Comment Commands. (line 40) 6945* indent-tabs-mode: Indentation Commands. 6946 (line 122) 6947* indentation-style (c-): Choosing a Style. (line 45) 6948* initialization-hook (c-): CC Hooks. (line 23) 6949* insert-tab-function (c-): Indentation Commands. 6950 (line 80) 6951* invalid-face (c-): Faces. (line 54) 6952* Java-defun-prompt-regexp (c-): Performance Issues. (line 39) 6953* java-font-lock-extra-types: Font Locking Preliminaries. 6954 (line 60) 6955* java-mode-hook: CC Hooks. (line 34) 6956* label-minimum-indentation (c-): Other Indentation. (line 12) 6957* macro-names-with-semicolon (c-): Macros with ;. (line 18) 6958* mark-wrong-style-of-comment (c-): Wrong Comment Style. (line 16) 6959* max-one-liner-length (c-): Clean-ups. (line 150) 6960* mode-common-hook (c-): CC Hooks. (line 28) 6961* noise-macro-names (c-): Noise Macros. (line 17) 6962* noise-macro-with-parens-names (c-): Noise Macros. (line 25) 6963* objc-font-lock-extra-types: Font Locking Preliminaries. 6964 (line 59) 6965* objc-mode-hook: CC Hooks. (line 33) 6966* offsets-alist (c-): Syntactic Symbols. (line 6) 6967* offsets-alist (c-) <1>: c-offsets-alist. (line 12) 6968* old-style-variable-behavior (c-): Style Variables. (line 19) 6969* paragraph-ignore-fill-prefix: Custom Filling and Breaking. 6970 (line 11) 6971* paragraph-separate: Custom Filling and Breaking. 6972 (line 11) 6973* paragraph-start: Custom Filling and Breaking. 6974 (line 11) 6975* pike-font-lock-extra-types: Font Locking Preliminaries. 6976 (line 62) 6977* pike-mode-hook: CC Hooks. (line 36) 6978* progress-interval (c-): Indentation Commands. 6979 (line 128) 6980* report-syntactic-errors (c-): Odds and Ends. (line 28) 6981* require-final-newline (c-): Odds and Ends. (line 9) 6982* special-indent-hook (c-): Other Indentation. (line 21) 6983* strict-syntax-p (c-): c-offsets-alist. (line 145) 6984* style-alist (c-): Adding Styles. (line 69) 6985* syntactic-context (c-): Custom Braces. (line 23) 6986* syntactic-context (c-) <1>: Custom Line-Up. (line 48) 6987* syntactic-element (c-): Custom Line-Up. (line 48) 6988* syntactic-indentation (c-): Indentation Engine Basics. 6989 (line 34) 6990* syntactic-indentation-in-macros (c-): Custom Macros. (line 17) 6991* tab-always-indent (c-): Indentation Commands. 6992 (line 67) 6993 6994 6995File: ccmode.info, Node: Concept and Key Index, Prev: Variable Index, Up: Top 6996 6997Concept and Key Index 6998********************* 6999 7000�[index�] 7001* Menu: 7002 7003* #: Electric Keys. (line 24) 7004* #define: Macro Backslashes. (line 6) 7005* (: Electric Keys. (line 62) 7006* ): Electric Keys. (line 63) 7007* *: Electric Keys. (line 37) 7008* ,: Electric Keys. (line 96) 7009* -block-intro symbols: Syntactic Symbols. (line 18) 7010* -close symbols: Syntactic Symbols. (line 18) 7011* -cont symbols: Syntactic Symbols. (line 24) 7012* -intro symbols: Syntactic Symbols. (line 24) 7013* -open symbols: Syntactic Symbols. (line 18) 7014* /: Electric Keys. (line 38) 7015* :: Electric Keys. (line 83) 7016* ;: Electric Keys. (line 95) 7017* <: Electric Keys. (line 53) 7018* >: Electric Keys. (line 54) 7019* {: Electric Keys. (line 75) 7020* }: Electric Keys. (line 76) 7021* Abbrev mode: Electric Keys. (line 124) 7022* access-label: Class Symbols. (line 40) 7023* action functions: Custom Braces. (line 6) 7024* Adaptive Fill mode: Custom Filling and Breaking. 7025 (line 58) 7026* anchor position: Indentation Engine Basics. 7027 (line 15) 7028* anchor position <1>: Syntactic Analysis. (line 30) 7029* annotation-top-cont: Java Symbols. (line 27) 7030* annotation-var-cont: Java Symbols. (line 27) 7031* announcement mailing list: Mailing Lists and Bug Reports. 7032 (line 29) 7033* arglist-close: Paren List Symbols. (line 29) 7034* arglist-cont: Paren List Symbols. (line 34) 7035* arglist-cont-nonempty: Paren List Symbols. (line 34) 7036* arglist-intro: Paren List Symbols. (line 29) 7037* Auto Fill mode: Filling and Breaking. 7038 (line 19) 7039* auto-newline: Auto-newlines. (line 6) 7040* AWK style: Built-in Styles. (line 44) 7041* awk-mode.el: Introduction. (line 6) 7042* Backspace: Hungry WS Deletion. (line 78) 7043* block-close: Conditional Construct Symbols. 7044 (line 28) 7045* block-open: Literal Symbols. (line 50) 7046* BOCM: Introduction. (line 6) 7047* brace lists: Brace List Symbols. (line 6) 7048* brace-entry-open: Brace List Symbols. (line 25) 7049* brace-list-close: Brace List Symbols. (line 19) 7050* brace-list-entry: Brace List Symbols. (line 19) 7051* brace-list-intro: Brace List Symbols. (line 19) 7052* brace-list-open: Brace List Symbols. (line 19) 7053* BSD style: Built-in Styles. (line 19) 7054* bug report mailing list: Mailing Lists and Bug Reports. 7055 (line 22) 7056* bugs: Limitations and Known Bugs. 7057 (line 6) 7058* c: Literal Symbols. (line 38) 7059* c++-mode.el: Introduction. (line 6) 7060* C-c .: Other Commands. (line 9) 7061* C-c :: Other Commands. (line 26) 7062* C-c Backspace: Hungry WS Deletion. (line 66) 7063* C-c C-a: Minor Modes. (line 69) 7064* C-c C-b: Mailing Lists and Bug Reports. 7065 (line 6) 7066* C-c C-Backspace: Hungry WS Deletion. (line 66) 7067* C-c C-c: Comment Commands. (line 11) 7068* C-c C-d: Hungry WS Deletion. (line 73) 7069* C-c C-DEL: Hungry WS Deletion. (line 66) 7070* C-c C-Delete: Hungry WS Deletion. (line 73) 7071* C-c C-e: Other Commands. (line 65) 7072* C-c C-k: Minor Modes. (line 60) 7073* C-c C-l: Minor Modes. (line 65) 7074* C-c C-n: Movement Commands. (line 96) 7075* C-c C-o: c-offsets-alist. (line 42) 7076* C-c C-o <1>: Interactive Customization. 7077 (line 72) 7078* C-c C-p: Movement Commands. (line 96) 7079* C-c C-q: Indentation Commands. 7080 (line 102) 7081* C-c C-s: Syntactic Analysis. (line 50) 7082* C-c C-u: Movement Commands. (line 66) 7083* C-c C-w: Minor Modes. (line 79) 7084* C-c C-z: Other Commands. (line 31) 7085* C-c C-\: Other Commands. (line 40) 7086* C-c DEL: Hungry WS Deletion. (line 66) 7087* C-c Delete: Hungry WS Deletion. (line 73) 7088* C-d: Hungry WS Deletion. (line 47) 7089* C-j: FAQ. (line 10) 7090* C-M-a (AWK Mode): Movement Commands. (line 38) 7091* C-M-e (AWK Mode): Movement Commands. (line 38) 7092* C-M-h: Indentation Commands. 7093 (line 115) 7094* C-M-q: Indentation Commands. 7095 (line 97) 7096* C-M-q <1>: FAQ. (line 61) 7097* C-M-u: FAQ. (line 61) 7098* C-M-\: Indentation Commands. 7099 (line 110) 7100* C-M-\ <1>: FAQ. (line 56) 7101* c-mode.el: Introduction. (line 6) 7102* C-x h: FAQ. (line 56) 7103* case-label: Switch Statement Symbols. 7104 (line 26) 7105* catch-clause: Conditional Construct Symbols. 7106 (line 44) 7107* class-close: Class Symbols. (line 27) 7108* class-open: Class Symbols. (line 27) 7109* clean-ups: Clean-ups. (line 6) 7110* comment handling: Filling and Breaking. 7111 (line 6) 7112* comment line prefix: Custom Filling and Breaking. 7113 (line 11) 7114* comment-intro: Literal Symbols. (line 33) 7115* comment-only line: Syntactic Analysis. (line 88) 7116* comments (insertion of): Comment Commands. (line 6) 7117* composition-close: External Scope Symbols. 7118 (line 38) 7119* composition-open: External Scope Symbols. 7120 (line 38) 7121* Configuration: Config Basics. (line 6) 7122* cpp-define-intro: Multiline Macro Symbols. 7123 (line 6) 7124* cpp-macro: Literal Symbols. (line 55) 7125* cpp-macro-cont: Multiline Macro Symbols. 7126 (line 6) 7127* customization, brace hanging: Custom Braces. (line 14) 7128* customization, colon hanging: Hanging Colons. (line 6) 7129* customization, comma newlines: Hanging Semicolons and Commas. 7130 (line 6) 7131* customization, indentation: Customizing Indentation. 7132 (line 6) 7133* customization, indentation functions: Custom Line-Up. (line 6) 7134* customization, interactive: Interactive Customization. 7135 (line 6) 7136* customization, semicolon newlines: Hanging Semicolons and Commas. 7137 (line 6) 7138* defun-block-intro: Function Symbols. (line 18) 7139* defun-close: Function Symbols. (line 18) 7140* defun-open: Function Symbols. (line 18) 7141* DEL: Hungry WS Deletion. (line 30) 7142* Delete: Hungry WS Deletion. (line 78) 7143* do-while-closure: Conditional Construct Symbols. 7144 (line 50) 7145* documentation comments: Doc Comments. (line 6) 7146* electric characters: Electric Keys. (line 6) 7147* Ellemtel style: Built-in Styles. (line 29) 7148* else-clause: Conditional Construct Symbols. 7149 (line 44) 7150* Emacs Initialization File: Config Basics. (line 6) 7151* extern-lang-close: External Scope Symbols. 7152 (line 15) 7153* extern-lang-open: External Scope Symbols. 7154 (line 15) 7155* faces: Faces. (line 6) 7156* file local variables: File Styles. (line 6) 7157* Filladapt mode: Custom Filling and Breaking. 7158 (line 72) 7159* Font Lock mode: Font Locking. (line 6) 7160* font locking: Font Locking. (line 6) 7161* friend: Class Symbols. (line 93) 7162* func-decl-cont: Literal Symbols. (line 31) 7163* GNU indent program: Indentation Commands. 7164 (line 12) 7165* GNU style: Built-in Styles. (line 10) 7166* GtkDoc markup: Doc Comments. (line 50) 7167* hanging braces: Hanging Braces. (line 6) 7168* hanging colons: Hanging Colons. (line 6) 7169* hanging commas: Hanging Semicolons and Commas. 7170 (line 6) 7171* hanging semicolons: Hanging Semicolons and Commas. 7172 (line 6) 7173* history: Introduction. (line 6) 7174* hungry-deletion: Hungry WS Deletion. (line 6) 7175* in-class inline methods: Class Symbols. (line 59) 7176* inclass: Class Symbols. (line 40) 7177* inclass <1>: External Scope Symbols. 7178 (line 15) 7179* incomposition: External Scope Symbols. 7180 (line 38) 7181* indentation: Indentation Commands. 7182 (line 6) 7183* indentation <1>: Indentation Calculation. 7184 (line 6) 7185* indentation <2>: Customizing Indentation. 7186 (line 6) 7187* indentation function: Line-Up Functions. (line 6) 7188* indentation offset specifications: Indentation Engine Basics. 7189 (line 21) 7190* inexpr-class: Java Symbols. (line 20) 7191* inexpr-statement: Statement Block Symbols. 7192 (line 16) 7193* inexpr-statement <1>: Statement Block Symbols. 7194 (line 58) 7195* inextern-lang: External Scope Symbols. 7196 (line 15) 7197* inher-cont: Class Symbols. (line 36) 7198* inher-intro: Class Symbols. (line 36) 7199* inlambda: Statement Block Symbols. 7200 (line 51) 7201* inline-close: Class Symbols. (line 59) 7202* inline-open: Class Symbols. (line 59) 7203* inmodule: External Scope Symbols. 7204 (line 35) 7205* innamespace: External Scope Symbols. 7206 (line 32) 7207* interactive customization: Interactive Customization. 7208 (line 6) 7209* Java style: Built-in Styles. (line 40) 7210* Javadoc markup: Filling and Breaking. 7211 (line 26) 7212* Javadoc markup <1>: Doc Comments. (line 44) 7213* Just-in-time Lock mode: Font Locking Preliminaries. 7214 (line 48) 7215* K&R style: Built-in Styles. (line 14) 7216* knr-argdecl: K&R Symbols. (line 6) 7217* knr-argdecl-intro: K&R Symbols. (line 6) 7218* label: Literal Symbols. (line 48) 7219* lambda-intro-cont: Statement Block Symbols. 7220 (line 51) 7221* Lazy Lock mode: Font Locking Preliminaries. 7222 (line 48) 7223* limitations: Limitations and Known Bugs. 7224 (line 6) 7225* line breaking: Filling and Breaking. 7226 (line 6) 7227* line-up function: Line-Up Functions. (line 6) 7228* Linux style: Built-in Styles. (line 34) 7229* literal: Indentation Commands. 7230 (line 67) 7231* literal <1>: Auto-newlines. (line 23) 7232* literal <2>: Clean-ups. (line 26) 7233* M-;: Comment Commands. (line 18) 7234* M-a: Movement Commands. (line 49) 7235* M-e: Movement Commands. (line 49) 7236* M-j: Filling and Breaking. 7237 (line 41) 7238* M-q: Filling and Breaking. 7239 (line 26) 7240* macros: Custom Macros. (line 6) 7241* macros with semicolons: Macros with ;. (line 6) 7242* member-init-cont: Class Symbols. (line 53) 7243* member-init-intro: Class Symbols. (line 53) 7244* Minor Modes: Minor Modes. (line 6) 7245* mode hooks: CC Hooks. (line 6) 7246* module-close: External Scope Symbols. 7247 (line 35) 7248* module-open: External Scope Symbols. 7249 (line 35) 7250* movement: Movement Commands. (line 6) 7251* multiline macros: Multiline Macro Symbols. 7252 (line 6) 7253* namespace-close: External Scope Symbols. 7254 (line 32) 7255* namespace-open: External Scope Symbols. 7256 (line 32) 7257* noise macros: Noise Macros. (line 6) 7258* nomenclature: Subword Movement. (line 6) 7259* objc-method-args-cont: Objective-C Method Symbols. 7260 (line 18) 7261* objc-method-call-cont: Objective-C Method Symbols. 7262 (line 18) 7263* objc-method-intro: Objective-C Method Symbols. 7264 (line 18) 7265* offset specification: c-offsets-alist. (line 60) 7266* offsets: Indentation Engine Basics. 7267 (line 21) 7268* open paren in column zero: FAQ. (line 80) 7269* paragraph filling: Filling and Breaking. 7270 (line 19) 7271* performance: Performance Issues. (line 6) 7272* Pike autodoc markup: Filling and Breaking. 7273 (line 26) 7274* Pike autodoc markup <1>: Doc Comments. (line 47) 7275* preprocessor directives: Custom Macros. (line 6) 7276* Python style: Built-in Styles. (line 37) 7277* RET: FAQ. (line 10) 7278* statement: Function Symbols. (line 28) 7279* statement-block-intro: Conditional Construct Symbols. 7280 (line 28) 7281* statement-case-intro: Switch Statement Symbols. 7282 (line 26) 7283* statement-case-open: Switch Statement Symbols. 7284 (line 26) 7285* statement-cont: Function Symbols. (line 28) 7286* stream-op: Literal Symbols. (line 64) 7287* string: Literal Symbols. (line 46) 7288* Stroustrup style: Built-in Styles. (line 26) 7289* style definition: Adding Styles. (line 13) 7290* style variables: Style Variables. (line 6) 7291* styles: Style Variables. (line 6) 7292* styles <1>: Styles. (line 6) 7293* styles, built-in: Built-in Styles. (line 6) 7294* styles, file local: File Styles. (line 6) 7295* substatement: Conditional Construct Symbols. 7296 (line 35) 7297* substatement <1>: Syntactic Analysis. (line 85) 7298* substatement block: Syntactic Analysis. (line 85) 7299* substatement-label: Conditional Construct Symbols. 7300 (line 39) 7301* substatement-open: Conditional Construct Symbols. 7302 (line 28) 7303* subword: Subword Movement. (line 6) 7304* syntactic analysis: Syntactic Analysis. (line 6) 7305* syntactic context: Syntactic Analysis. (line 6) 7306* syntactic element: Syntactic Analysis. (line 6) 7307* syntactic symbol: Indentation Engine Basics. 7308 (line 15) 7309* syntactic symbol <1>: Syntactic Analysis. (line 22) 7310* syntactic symbols, brief list: Syntactic Symbols. (line 6) 7311* syntactic whitespace: Auto-newlines. (line 23) 7312* syntactic whitespace <1>: Literal Symbols. (line 40) 7313* syntactic whitespace <2>: Multiline Macro Symbols. 7314 (line 6) 7315* TAB: Indentation Commands. 7316 (line 42) 7317* template-args-cont: Class Symbols. (line 103) 7318* text filling: Filling and Breaking. 7319 (line 6) 7320* topmost-intro: Function Symbols. (line 18) 7321* topmost-intro-cont: Function Symbols. (line 18) 7322* types, user defined: Font Locking Preliminaries. 7323 (line 54) 7324* user defined types: Font Locking Preliminaries. 7325 (line 54) 7326* User style: Built-in Styles. (line 48) 7327* web site: Updating CC Mode. (line 9) 7328* Whitesmith style: Built-in Styles. (line 22) 7329 7330 7331 7332Tag Table: 7333Node: Top968 7334Node: Introduction4119 7335Ref: Introduction-Footnote-16133 7336Node: Overview6267 7337Node: Getting Started8212 7338Ref: Getting Started-Footnote-112449 7339Node: Commands12527 7340Node: Indentation Commands13361 7341Ref: Indentation Commands-Footnote-120110 7342Node: Comment Commands20231 7343Ref: Comment Commands-Footnote-122874 7344Node: Movement Commands22941 7345Ref: Movement Commands-Footnote-128581 7346Node: Filling and Breaking28642 7347Ref: Filling and Breaking-Footnote-132143 7348Ref: Filling and Breaking-Footnote-232288 7349Node: Minor Modes32352 7350Ref: Minor Modes-Footnote-136620 7351Ref: Minor Modes-Footnote-236773 7352Ref: Minor Modes-Footnote-336895 7353Ref: Minor Modes-Footnote-436967 7354Node: Electric Keys37039 7355Node: Auto-newlines42846 7356Ref: Auto-newlines-Footnote-144708 7357Node: Hungry WS Deletion44917 7358Ref: Hungry WS Deletion-Footnote-150667 7359Ref: Hungry WS Deletion-Footnote-250816 7360Node: Subword Movement50885 7361Node: Other Commands53293 7362Node: Font Locking56796 7363Node: Font Locking Preliminaries57694 7364Node: Faces61763 7365Node: Doc Comments64486 7366Node: Wrong Comment Style67589 7367Node: Misc Font Locking68429 7368Node: AWK Mode Font Locking70005 7369Node: Config Basics72502 7370Ref: Config Basics-Footnote-179380 7371Ref: Config Basics-Footnote-279429 7372Node: CC Hooks79571 7373Node: Style Variables82024 7374Ref: Style Variables-Footnote-185411 7375Ref: Style Variables-Footnote-285817 7376Node: Styles85862 7377Node: Built-in Styles87216 7378Ref: Built-in Styles-Footnote-189163 7379Ref: Built-in Styles-Footnote-289269 7380Node: Choosing a Style89414 7381Node: Adding Styles91519 7382Ref: Adding Styles-Footnote-194909 7383Ref: Adding Styles-Footnote-294983 7384Node: Guessing the Style95217 7385Node: File Styles99459 7386Ref: File Styles-Footnote-1101070 7387Node: Custom Filling and Breaking101372 7388Ref: Custom Filling and Breaking-Footnote-1108149 7389Ref: Custom Filling and Breaking-Footnote-2108405 7390Ref: Custom Filling and Breaking-Footnote-3108696 7391Ref: Custom Filling and Breaking-Footnote-4108880 7392Node: Custom Auto-newlines109159 7393Node: Hanging Braces111025 7394Ref: Hanging Braces-Footnote-1116601 7395Ref: Hanging Braces-Footnote-2116688 7396Ref: Hanging Braces-Footnote-3116847 7397Node: Custom Braces117064 7398Node: Hanging Colons120491 7399Node: Hanging Semicolons and Commas122086 7400Ref: Hanging Semicolons and Commas-Footnote-1125178 7401Node: Clean-ups125229 7402Ref: Clean-ups-Footnote-1132049 7403Node: Indentation Engine Basics132254 7404Node: Syntactic Analysis134572 7405Ref: Syntactic Analysis-Footnote-1138537 7406Ref: Syntactic Analysis-Footnote-2138814 7407Ref: Syntactic Analysis-Footnote-3138917 7408Ref: Syntactic Analysis-Footnote-4139052 7409Node: Syntactic Symbols139288 7410Node: Function Symbols149487 7411Node: Class Symbols150689 7412Ref: Class Symbols-Footnote-1155139 7413Node: Conditional Construct Symbols155366 7414Ref: Conditional Construct Symbols-Footnote-1157700 7415Node: Switch Statement Symbols157833 7416Node: Brace List Symbols158777 7417Ref: Brace List Symbols-Footnote-1160687 7418Node: External Scope Symbols161008 7419Ref: External Scope Symbols-Footnote-1162478 7420Node: Paren List Symbols162626 7421Node: Literal Symbols164747 7422Node: Multiline Macro Symbols167341 7423Ref: Multiline Macro Symbols-Footnote-1168937 7424Node: Objective-C Method Symbols168999 7425Node: Java Symbols169781 7426Node: Statement Block Symbols171087 7427Ref: Statement Block Symbols-Footnote-1173788 7428Node: K&R Symbols174113 7429Ref: K&R Symbols-Footnote-1174748 7430Node: Indentation Calculation174795 7431Node: Customizing Indentation178115 7432Node: c-offsets-alist179759 7433Ref: c-offsets-alist-Footnote-1186491 7434Ref: c-offsets-alist-Footnote-2186610 7435Node: Interactive Customization186957 7436Ref: Interactive Customization-Footnote-1189965 7437Node: Line-Up Functions190108 7438Node: Brace/Paren Line-Up191978 7439Ref: c-lineup-arglist-close-under-paren193065 7440Ref: Brace/Paren Line-Up-Footnote-1198634 7441Node: List Line-Up198776 7442Node: Operator Line-Up207046 7443Node: Comment Line-Up211262 7444Node: Misc Line-Up214120 7445Ref: Misc Line-Up-Footnote-1219054 7446Node: Custom Line-Up219377 7447Ref: Custom Line-Up-Footnote-1224033 7448Node: Other Indentation224194 7449Ref: Other Indentation-Footnote-1226246 7450Node: Custom Macros226448 7451Node: Macro Backslashes228044 7452Node: Macros with ;230045 7453Node: Noise Macros232238 7454Ref: Noise Macros-Footnote-1234651 7455Node: Odds and Ends234761 7456Node: Sample Init File236454 7457Node: Performance Issues238794 7458Ref: Performance Issues-Footnote-1244387 7459Ref: Performance Issues-Footnote-2244464 7460Node: Limitations and Known Bugs244528 7461Node: FAQ247053 7462Ref: FAQ-Footnote-1251015 7463Node: Updating CC Mode251087 7464Node: Mailing Lists and Bug Reports251687 7465Node: GNU Free Documentation License253732 7466Node: Command and Function Index279122 7467Node: Variable Index300738 7468Node: Concept and Key Index315964 7469 7470End Tag Table 7471 7472 7473Local Variables: 7474coding: utf-8 7475End: 7476