-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcc-mode.texi
7243 lines (6129 loc) · 264 KB
/
cc-mode.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo
@c Notes to self regarding line handling:
@c
@c Empty lines are often significant before @end directives; avoid them.
@c
@c Empty lines before and after @example directives are significant in
@c info output but not in TeX. Empty lines inside @example directives
@c are significant.
@c Conventions for formatting examples:
@c o If the example contains empty lines then put the surrounding empty
@c lines inside the @example directives. Put them outside otherwise.
@c o Use @group inside the example only if it shows indentation where
@c the relation between lines inside is relevant.
@c o Format line number columns like this:
@c 1: foo
@c 2: bar
@c ^ one space
@c ^^ two columns, right alignment
@c o Check line lengths in TeX output; they can typically be no longer
@c than 70 chars, 60 if the paragraph is indented.
@comment TBD: Document the finer details of statement anchoring?
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment %**start of header (This is for running Texinfo on a region)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment How to make the various output formats:
@comment (Thanks to Robert Chassell for supplying this information.)
@comment Note that Texinfo 4.7 (or later) is needed.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@ignore
In each of the following pairs of commands, the first generates a
version with cross references pointing to the GNU Emacs manuals,
the second with them pointing to the XEmacs manuals.
## Info output
makeinfo cc-mode.texi
makeinfo -DXEMACS cc-mode.texi
## DVI output
## You may need to set up the environment variable TEXINPUTS so
## that tex can find the file texinfo.tex - See the tex
## manpage.
texi2dvi cc-mode.texi
texi2dvi -t "@set XEMACS " cc-mode.texi
## HTML output. (The --no-split parameter is optional)
makeinfo --html --no-split cc-mode.texi
makeinfo --html --no-split -DXEMACS cc-mode.texi
## Plain text output
makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
--no-headers --output=cc-mode.txt cc-mode.texi
makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
--no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi
## DocBook output
makeinfo --docbook --no-split --paragraph-indent=0 \
cc-mode.texi
makeinfo --docbook --no-split --paragraph-indent=0 \
-DXEMACS cc-mode.texi
## XML output
makeinfo --xml --no-split --paragraph-indent=0 \
cc-mode.texi
makeinfo --xml --no-split --paragraph-indent=0 \
-DXEMACS cc-mode.texi
#### (You must be in the same directory as the viewed file.)
## View DVI output
xdvi cc-mode.dvi &
## View HTML output
mozilla cc-mode.html
@end ignore
@comment No overfull hbox marks in the dvi file.
@finalout
@setfilename cc-mode.info
@settitle CC Mode Manual
@footnotestyle end
@c The following four macros generate the filenames and titles of the
@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it
@c to generate an XEmacs version, e.g. with
@c "makeinfo -DXEMACS cc-mode.texi".
@ifset XEMACS
@macro emacsman
xemacs
@end macro
@macro emacsmantitle
XEmacs User's Manual
@end macro
@macro lispref
lispref
@end macro
@macro lispreftitle
XEmacs Lisp Reference Manual
@end macro
@end ifset
@ifclear XEMACS
@macro emacsman
emacs
@end macro
@macro emacsmantitle
GNU Emacs Manual
@end macro
@macro lispref
elisp
@end macro
@macro lispreftitle
GNU Emacs Lisp Reference Manual
@end macro
@end ifclear
@macro ccmode
CC Mode
@end macro
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment @setchapternewpage odd !! we don't want blank pages !!
@comment %**end of header (This is for running Texinfo on a region)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment
@comment Texinfo manual for CC Mode
@comment Generated from the original README file by Krishna Padmasola
@comment <[email protected]>
@comment
@comment Authors:
@comment Barry A. Warsaw
@comment Martin Stjernholm
@comment Alan Mackenzie
@comment
@comment Maintained by Martin Stjernholm and Alan Mackenzie <[email protected]>
@comment
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment Define an index for syntactic symbols.
@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
@c For Info, unlike tex, @syncodeindex needs a matching @defindex.
@defindex ss
@end ifnottex
@comment Combine key, syntactic symbol and concept indices into one.
@syncodeindex ss cp
@syncodeindex ky cp
@copying
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
Foundation, Inc.
This manual is free documentation; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 3, or (at
your option) any later version.
This manual is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License, the
file @file{COPYING}, along with @ccmode{}. If not, see
@url{http://www.gnu.org/licenses/gpl.html}.
@end copying
@comment Info directory entry for use by install-info. The indentation
@comment here is by request from the FSF folks.
@dircategory Emacs
@direntry
* CC Mode: (cc-mode). Emacs mode for editing C, C++, Objective-C,
Java, Pike, AWK, and CORBA IDL code.
@end direntry
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment TeX title page
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@titlepage
@sp 10
@center @titlefont{CC Mode 5.32}
@sp 2
@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
@sp 2
@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
@page
@vskip 0pt plus 1filll
@insertcopying
This manual was generated from $Revision: 5.266 $ of $RCSfile: cc-mode.texi,v $, which can be
downloaded from
@url{http://cvs.sf.net/viewcvs.py/cc-mode/cc-mode/cc-mode.texi}.
@end titlepage
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment The Top node contains the master menu for the Info file.
@comment This appears only in the Info file, not the printed manual.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@ifinfo
@top @ccmode{}
@ccmode{} is a GNU Emacs mode for editing files containing C, C++,
Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
and AWK code. It provides syntax-based indentation, font locking, and
has several handy commands and some minor modes to make the editing
easier. It does not provide tools to look up and navigate between
functions, classes etc - there are other packages for that.
@end ifinfo
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@menu
* Introduction::
* Overview::
* Getting Started::
* Commands::
* Font Locking::
* Config Basics::
* Custom Filling and Breaking::
* Custom Auto-newlines::
* Clean-ups::
* Indentation Engine Basics::
* Customizing Indentation::
* Custom Macros::
* Odds and Ends::
* Sample .emacs File::
* Performance Issues::
* Limitations and Known Bugs::
* FAQ::
* Updating CC Mode::
* Mailing Lists and Bug Reports::
* Command and Function Index::
* Variable Index::
* Concept and Key Index::
@detailmenu
--- The Detailed Node Listing ---
Commands
* Indentation Commands::
* Comment Commands::
* Movement Commands::
* Filling and Breaking::
* Minor Modes::
* Electric Keys::
* Auto-newlines::
* Hungry WS Deletion::
* Subword Movement::
* Other Commands::
Font Locking
* Font Locking Preliminaries::
* Faces::
* Doc Comments::
* AWK Mode Font Locking::
Configuration Basics
* CC Hooks::
* Style Variables::
* Styles::
Styles
* Built-in Styles::
* Choosing a Style::
* Adding Styles::
* Guessing the Style::
* File Styles::
Customizing Auto-newlines
* Hanging Braces::
* Hanging Colons::
* Hanging Semicolons and Commas::
Hanging Braces
* Custom Braces::
Indentation Engine Basics
* Syntactic Analysis::
* Syntactic Symbols::
* Indentation Calculation::
Syntactic Symbols
* Function Symbols::
* Class Symbols::
* Conditional Construct Symbols::
* Switch Statement Symbols::
* Brace List Symbols::
* External Scope Symbols::
* Paren List Symbols::
* Literal Symbols::
* Multiline Macro Symbols::
* Objective-C Method Symbols::
* Java Symbols::
* Statement Block Symbols::
* K&R Symbols::
Customizing Indentation
* c-offsets-alist::
* Interactive Customization::
* Line-Up Functions::
* Custom Line-Up::
* Other Indentation::
Line-Up Functions
* Brace/Paren Line-Up::
* List Line-Up::
* Operator Line-Up::
* Comment Line-Up::
* Misc Line-Up::
Customizing Macros
* Macro Backslashes::
* Macros with ;::
@end detailmenu
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Introduction, Overview, Top, Top
@comment node-name, next, previous, up
@chapter Introduction
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@cindex BOCM
@cindex history
@cindex awk-mode.el
@cindex c-mode.el
@cindex c++-mode.el
Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
CIDL), Pike and AWK code. This incarnation of the mode is descended
from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
in the (X)Emacs base.
Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
Maintainers Team, and implemented the Pike support. In 2000 Martin
took over as the sole maintainer. In 2001 Alan Mackenzie joined the
team, implementing AWK support in version 5.30. @ccmode{} did not
originally contain the font lock support for its languages --- that
was added in version 5.30.
This manual describes @ccmode{}
@comment The following line must appear on its own, so that the
version 5.32.
@comment Release.py script can update the version number automatically
@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
scripting language with its roots in the LPC language used in some MUD
engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
way, you can easily set up consistent font locking and coding styles for
use in editing all of these languages, although AWK is not yet as
uniformly integrated as the other languages.
@findex c-mode
@findex c++-mode
@findex objc-mode
@findex java-mode
@findex idl-mode
@findex pike-mode
@findex awk-mode
Note that the name of this package is ``@ccmode{}'', but there is no top
level @code{cc-mode} entry point. All of the variables, commands, and
functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
provided. This package is intended to be a replacement for
@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
A special word of thanks goes to Krishna Padmasola for his work in
converting the original @file{README} file to Texinfo format. I'd
also like to thank all the @ccmode{} victims who help enormously
during the early beta stages of @ccmode{}'s development.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Overview, Getting Started, Introduction, Top
@comment node-name, next, previous, up@cindex organization of the manual
@chapter Overview of the Manual
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@noindent
The manual starts with several introductory chapters (including this
one).
@noindent
The next chunk of the manual describes the day to day @emph{use} of
@ccmode{} (as contrasted with how to customize it).
@itemize @bullet
@item
The chapter ``Commands'' describes in detail how to use (nearly) all
of @ccmode{}'s features. There are extensive cross-references from
here to the corresponding sections later in the manual which tell you
how to customize these features.
@item
``Font Locking'' describes how ``syntax highlighting'' is applied to
your buffers. It is mainly background information and can be skipped
over at a first reading.
@end itemize
@noindent
The next chunk of the manual describes how to @emph{customize}
@ccmode{}. Typically, an overview of a topic is given at the chapter
level, then the sections and subsections describe the material in
increasing detail.
@itemize @bullet
@item
The chapter ``Configuration Basics'' tells you @emph{how} to write
customizations - whether in hooks, in styles, in both, or in neither,
depending on your needs. It describes the @ccmode{} style system and
lists the standard styles that @ccmode{} supplies.
@item
The next few chapters describe in detail how to customize the various
features of @ccmode{}.
@item
Finally, there is a sample @file{.emacs} fragment, which might help you
in creating your own customization.
@end itemize
@noindent
The manual ends with ``this and that'', things that don't fit cleanly
into any of the previous chunks.
@itemize @bullet
@item
Two chapters discuss the performance of @ccmode{} and known
bugs/limitations.
@item
The FAQ contains a list of common problems and questions.
@item
The next two chapters tell you how to get in touch with the @ccmode{}
project - whether for updating @ccmode{} or submitting bug reports.
@end itemize
@noindent
Finally, there are the customary indices.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Getting Started, Commands, Overview, Top
@comment node-name, next, previous, up
@chapter Getting Started
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
If you got this version of @ccmode{} with Emacs or XEmacs, it should
work just fine right out of the box. Note however that you might not
have the latest @ccmode{} release and might want to upgrade your copy
(see below).
You should probably start by skimming through the entire chapter
@ref{Commands} to get an overview of @ccmode{}'s capabilities.
After trying out some commands, you may dislike some aspects of
@ccmode{}'s default configuration. Here is an outline of how to
change some of the settings that newcomers to @ccmode{} most often
want to change:
@table @asis
@item c-basic-offset
This Lisp variable holds an integer, the number of columns @ccmode{}
indents nested code. To set this value to 6, customize
@code{c-basic-offset} or put this into your @file{.emacs}:
@example
(setq c-basic-offset 6)
@end example
@item The (indentation) style
The basic ``shape'' of indentation created by @ccmode{}---by default,
this is @code{gnu} style (except for Java and AWK buffers). A list of
the available styles and their descriptions can be found in
@ref{Built-in Styles}. A complete specification of the @ccmode{}
style system, including how to create your own style, can be found in
the chapter @ref{Styles}. To set your style to @code{linux}, either
customize @code{c-default-style} or put this into your @file{.emacs}:
@example
(setq c-default-style '((java-mode . "java")
(awk-mode . "awk")
(other . "linux")))
@end example
@item Electric Indentation
Normally, when you type ``punctuation'' characters such as @samp{;} or
@samp{@{}, @ccmode{} instantly reindents the current line. This can
be disconcerting until you get used to it. To disable @dfn{electric
indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
thing to enable it again. To have electric indentation disabled by
default, put the following into your @file{.emacs} file@footnote{There
is no ``easy customization'' facility for making this change.}:
@example
(setq-default c-electric-flag nil)
@end example
@noindent
Details of this and other similar ``Minor Modes'' appear in the
section @ref{Minor Modes}.
@item Making the @key{RET} key indent the new line
The standard Emacs binding for @key{RET} just adds a new line. If you
want it to reindent the new line as well, rebind the key. Note that
the action of rebinding would fail if the pertinent keymap didn't yet
exist---we thus need to delay the action until after @ccmode{} has
been loaded. Put the following code into your @file{.emacs}:
@example
(defun my-make-CR-do-indent ()
(define-key c-mode-base-map "\C-m" 'c-context-line-break))
(add-hook 'c-initialization-hook 'my-make-CR-do-indent)
@end example
@noindent
This example demonstrates the use of a very powerful @ccmode{} (and
Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
in @ref{CC Hooks}.
@end table
All these settings should occur in your @file{.emacs} @emph{before}
any @ccmode{} buffers get loaded---in particular, before any call of
@code{desktop-read}.
As you get to know the mode better, you may want to make more
ambitious changes to your configuration. For this, you should start
reading the chapter @ref{Config Basics}.
If you are upgrading an existing @ccmode{} installation, please see
the @file{README} file for installation details. In particular, if
you are going to be editing AWK files, @file{README} describes how to
configure your (X)Emacs so that @ccmode{} will supersede the obsolete
@code{awk-mode.el} which might have been supplied with your (X)Emacs.
@ccmode{} might not work with older versions of Emacs or XEmacs. See
the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
for the latest information on Emacs version and package compatibility
(@pxref{Updating CC Mode}).
@deffn Command c-version
@findex version (c-)
You can find out what version of @ccmode{} you are using by visiting a C
file and entering @kbd{M-x c-version RET}. You should see this message in
the echo area:
@example
Using CC Mode version 5.XX
@end example
@noindent
where @samp{XX} is the minor release number.
@end deffn
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Commands, Font Locking, Getting Started, Top
@comment node-name, next, previous, up
@chapter Commands
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
This chapter specifies all of CC Mode's commands, and thus contains
nearly everything you need to know to @emph{use} @ccmode{} (as
contrasted with configuring it). @dfn{Commands} here means both
control key sequences and @dfn{electric keys}, these being characters
such as @samp{;} which, as well as inserting themselves into the
buffer, also do other things.
You might well want to review
@ifset XEMACS
@ref{Lists,,,@emacsman{}, @emacsmantitle{}},
@end ifset
@ifclear XEMACS
@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
@end ifclear
which describes commands for moving around brace and parenthesis
structures.
@menu
* Indentation Commands::
* Comment Commands::
* Movement Commands::
* Filling and Breaking::
* Minor Modes::
* Electric Keys::
* Auto-newlines::
* Hungry WS Deletion::
* Subword Movement::
* Other Commands::
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Indentation Commands, Comment Commands, Commands, Commands
@comment node-name, next, previous,up
@section Indentation Commands
@cindex indentation
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
The following commands reindent C constructs. Note that when you
change your coding style, either interactively or through some other
means, your file does @emph{not} automatically get reindented. You
will need to execute one of the following commands to see the effects
of your changes.
@cindex GNU indent program
Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
formatted. Changing the ``hanginess'' of a brace and then
reindenting, will not move the brace to a different line. For this,
you're better off getting an external program like GNU @code{indent},
which will rearrange brace location, amongst other things.
Preprocessor directives are handled as syntactic whitespace from other
code, i.e. they can be interspersed anywhere without affecting the
indentation of the surrounding code, just like comments.
The code inside macro definitions is, by default, still analyzed
syntactically so that you get relative indentation there just as you'd
get if the same code was outside a macro. However, since there is no
hint about the syntactic context, i.e. whether the macro expands to an
expression, to some statements, or perhaps to whole functions, the
syntactic recognition can be wrong. @ccmode{} manages to figure it
out correctly most of the time, though.
Some macros, when invoked, ''have their own semicolon''. To get the
next line indented correctly, rather than as a continuation line,
@xref{Macros with ;}.
Reindenting large sections of code can take a long time. When
@ccmode{} reindents a region of code, it is essentially equivalent to
hitting @key{TAB} on every line of the region.
These commands indent code:
@table @asis
@item @kbd{@key{TAB}} (@code{c-indent-command})
@kindex TAB
@findex c-indent-command
@findex indent-command (c-)
This command indents the current line. That is all you need to know
about it for normal use.
@code{c-indent-command} does different things, depending on the
setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
Basics}):
@itemize @bullet
@item
When it's non-@code{nil} (which it normally is), the command indents
the line according to its syntactic context. With a prefix argument
(@kbd{C-u @key{TAB}}), it will re-indent the entire
expression@footnote{this is only useful for a line starting with a
comment opener or an opening brace, parenthesis, or string quote.}
that begins at the line's left margin.
@item
When it's @code{nil}, the command indents the line by an extra
@code{c-basic-offset} columns. A prefix argument acts as a
multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
removing @code{c-basic-offset} columns from the indentation.
@end itemize
The precise behavior is modified by several variables: With
@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
in some circumstances---@code{c-insert-tab-function} then defines
precisely what sort of ``whitespace'' this will be. Set the standard
Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
@samp{tab} characters to be used in the indentation, to @code{nil} if
you want only spaces. @xref{Just Spaces,,, @emacsman{},
@emacsmantitle{}}.
@defopt c-tab-always-indent
@vindex tab-always-indent (c-)
@cindex literal
This variable modifies how @key{TAB} operates.
@itemize @bullet
@item
When it is @code{t} (the default), @key{TAB} simply indents the
current line.
@item
When it is @code{nil}, @key{TAB} (re)indents the line only if point is
to the left of the first non-whitespace character on the line.
Otherwise it inserts some whitespace (a tab or an equivalent number of
spaces - see below) at point.
@item
With some other value, the line is reindented. Additionally, if point
is within a string or comment, some whitespace is inserted.
@end itemize
@end defopt
@defopt c-insert-tab-function
@vindex insert-tab-function (c-)
@findex tab-to-tab-stop
When ``some whitespace'' is inserted as described above, what actually
happens is that the function stored in @code{c-insert-tab-function} is
called. Normally, this is @code{insert-tab}, which inserts a real tab
character or the equivalent number of spaces (depending on
@code{indent-tabs-mode}). Some people, however, set
@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
hard tab stops when indenting.
@end defopt
@end table
@noindent
The kind of indentation the next five commands do depends on the
setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
Basics}):
@itemize @bullet
@item
when it is non-@code{nil} (the default), the commands indent lines
according to their syntactic context;
@item
when it is @code{nil}, they just indent each line the same amount as
the previous non-blank line. The commands that indent a region aren't
very useful in this case.
@end itemize
@table @asis
@item @kbd{C-j} (@code{newline-and-indent})
@kindex C-j
@findex newline-and-indent
Inserts a newline and indents the new blank line, ready to start
typing. This is a standard (X)Emacs command.
@item @kbd{C-M-q} (@code{c-indent-exp})
@kindex C-M-q
@findex c-indent-exp
@findex indent-exp (c-)
Indents an entire balanced brace or parenthesis expression. Note that
point must be on the opening brace or parenthesis of the expression
you want to indent.
@item @kbd{C-c C-q} (@code{c-indent-defun})
@kindex C-c C-q
@findex c-indent-defun
@findex indent-defun (c-)
Indents the entire top-level function, class or macro definition
encompassing point. It leaves point unchanged. This function can't be
used to reindent a nested brace construct, such as a nested class or
function, or a Java method. The top-level construct being reindented
must be complete, i.e. it must have both a beginning brace and an ending
brace.
@item @kbd{C-M-\} (@code{indent-region})
@kindex C-M-\
@findex indent-region
Indents an arbitrary region of code. This is a standard Emacs command,
tailored for C code in a @ccmode{} buffer. Note, of course, that point
and mark must delineate the region you want to indent.
@item @kbd{C-M-h} (@code{c-mark-function})
@kindex C-M-h
@findex c-mark-function
@findex mark-function (c-)
While not strictly an indentation command, this is useful for marking
the current top-level function or class definition as the current
region. As with @code{c-indent-defun}, this command operates on
top-level constructs, and can't be used to mark say, a Java method.
@end table
These variables are also useful when indenting code:
@defopt indent-tabs-mode
This is a standard Emacs variable that controls how line indentation
is composed. When it's non-@code{nil}, tabs can be used in a line's
indentation, otherwise only spaces are used.
@end defopt
@defopt c-progress-interval
@vindex progress-interval (c-)
When indenting large regions of code, this variable controls how often a
progress message is displayed. Set this variable to @code{nil} to
inhibit the progress messages, or set it to an integer which is how
often (in seconds) progress messages are to be displayed.
@end defopt
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Comment Commands, Movement Commands, Indentation Commands, Commands
@comment node-name, next, previous, up
@section Comment Commands
@cindex comments (insertion of)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@table @asis
@item @kbd{C-c C-c} (@code{comment-region})
@kindex C-c C-c
@findex comment-region
This command comments out the lines that start in the region. With a
negative argument, it does the opposite - it deletes the comment
delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
Emacs Manual}, for fuller details. @code{comment-region} isn't
actually part of @ccmode{} - it is given a @ccmode{} binding for
convenience.
@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
@kindex M-;
@findex comment-dwim
@findex indent-for-comment
Insert a comment at the end of the current line, if none is there
already. Then reindent the comment according to @code{comment-column}
@ifclear XEMACS
(@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
@end ifclear
@ifset XEMACS
(@pxref{Comments,,, xemacs, XEmacs User's Manual})
@end ifset
and the variables below. Finally, position the point after the
comment starter. @kbd{C-u M-;} kills any comment on the current line,
together with any whitespace before it. This is a standard Emacs
command, but @ccmode{} enhances it a bit with two variables:
@defopt c-indent-comment-alist
@vindex indent-comment-alist (c-)
@vindex comment-column
This style variable allows you to vary the column that @kbd{M-;} puts
the comment at, depending on what sort of code is on the line, and
possibly the indentation of any similar comment on the preceding line.
It is an association list that maps different types of lines to
actions describing how they should be handled. If a certain line type
isn't present on the list then the line is indented to the column
specified by @code{comment-column}.
See the documentation string for a full description of this
variable (use @kbd{C-h v c-indent-comment-alist}).
@end defopt
@defopt c-indent-comments-syntactically-p
@vindex indent-comments-syntactically-p (c-)
Normally, when this style variable is @code{nil}, @kbd{M-;} will
indent comment-only lines according to @code{c-indent-comment-alist},
just as it does with lines where other code precede the comments.
However, if you want it to act just like @key{TAB} for comment-only
lines you can get that by setting
@code{c-indent-comments-syntactically-p} to non-@code{nil}.
If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
@code{c-indent-comment-alist} won't be consulted at all for comment-only
lines.
@end defopt
@end table
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Movement Commands, Filling and Breaking, Comment Commands, Commands
@comment node-name, next, previous, up
@section Movement Commands
@cindex movement
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@ccmode{} contains some useful commands for moving around in C code.
@table @asis
@item @kbd{C-M-a} (@code{c-beginning-of-defun})
@itemx @kbd{C-M-e} (@code{c-end-of-defun})
@findex c-beginning-of-defun
@findex c-end-of-defun
@vindex c-defun-tactic
@vindex defun-tactic (c-)
Move to the beginning or end of the current or next function. Other
constructs (such as a structs or classes) which have a brace block
also count as ``functions'' here. To move over several functions, you
can give these commands a repeat count.
The start of a function is at its header. The end of the function is
after its closing brace, or after the semicolon of a construct (such
as a @code{struct}) which doesn't end at the brace. These two
commands try to leave point at the beginning of a line near the actual
start or end of the function. This occasionally causes point not to
move at all.
By default, these commands will recognize functions contained within a
@dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
construct, should the point start inside it. If @ccmode fails to find
function beginnings or ends inside the current declaration scope, it
will search the enclosing scopes. If you want @ccmode to recognize
functions only at the top level@footnote{this was @ccmode{}'s
behavior prior to version 5.32.}, set @code{c-defun-tactic} to
@code{t}.
These functions are analogous to the Emacs built-in commands
@code{beginning-of-defun} and @code{end-of-defun}, except they
eliminate the constraint that the top-level opening brace of the defun
must be in column zero. See @ref{Defuns,,,@emacsman{},
@emacsmantitle{}}, for more information.
@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
@kindex C-M-a (AWK Mode)
@kindex C-M-e (AWK Mode)
@findex c-awk-beginning-of-defun
@findex awk-beginning-of-defun (c-)
@findex c-awk-end-of-defun
@findex awk-end-of-defun (c-)
Move to the beginning or end of the current or next AWK defun. These
commands can take prefix-arguments, their functionality being entirely
equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
might be implicit) or user defined functions. Having the @samp{@{} and
@samp{@}} (if there are any) in column zero, as is suggested for some
modes, is neither necessary nor helpful in AWK mode.
@item @kbd{M-a} (@code{c-beginning-of-statement})
@itemx @kbd{M-e} (@code{c-end-of-statement})
@kindex M-a
@kindex M-e
@findex c-beginning-of-statement
@findex c-end-of-statement
@findex beginning-of-statement (c-)
@findex end-of-statement (c-)
Move to the beginning or end of the innermost C statement. If point
is already there, move to the next beginning or end of a statement,
even if that means moving into a block. (Use @kbd{C-M-b} or
@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
means move over @var{n} statements.
If point is within or next to a comment or a string which spans more
than one line, these commands move by sentences instead of statements.
When called from a program, these functions take three optional
arguments: the repetition count, a buffer position limit which is the
farthest back to search for the syntactic context, and a flag saying
whether to do sentence motion in or near comments and multiline
strings.
@item @kbd{C-c C-u} (@code{c-up-conditional})
@kindex C-c C-u
@findex c-up-conditional
@findex up-conditional (c-)
Move back to the containing preprocessor conditional, leaving the mark
behind. A prefix argument acts as a repeat count. With a negative
argument, move forward to the end of the containing preprocessor
conditional.
@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
function stops at them when going backward, but not when going
forward.
This key sequence is not bound in AWK Mode, which doesn't have
preprocessor statements.
@item @kbd{M-x c-up-conditional-with-else}
@findex c-up-conditional-with-else
@findex up-conditional-with-else (c-)
A variety of @code{c-up-conditional} that also stops at @samp{#else}
lines. Normally those lines are ignored.
@item @kbd{M-x c-down-conditional}
@findex c-down-conditional
@findex down-conditional (c-)
Move forward into the next nested preprocessor conditional, leaving
the mark behind. A prefix argument acts as a repeat count. With a
negative argument, move backward into the previous nested preprocessor
conditional.
@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
function stops at them when going forward, but not when going backward.
@item @kbd{M-x c-down-conditional-with-else}
@findex c-down-conditional-with-else
@findex down-conditional-with-else (c-)
A variety of @code{c-down-conditional} that also stops at @samp{#else}
lines. Normally those lines are ignored.
@item @kbd{C-c C-p} (@code{c-backward-conditional})
@itemx @kbd{C-c C-n} (@code{c-forward-conditional})