|
32
|
1 \input texinfo
|
|
0
|
2
|
|
|
3 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
4 @comment %**start of header (This is for running Texinfo on a region)
|
|
|
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
6
|
|
32
|
7 @setfilename cc-mode.info
|
|
|
8 @settitle CC MODE Version 4 Documentation
|
|
0
|
9 @footnotestyle end
|
|
|
10
|
|
|
11 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
12 @comment @setchapternewpage odd !! we don't want blank pages !!
|
|
|
13 @comment %**end of header (This is for running Texinfo on a region)
|
|
|
14 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
15
|
|
|
16
|
|
|
17 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
18 @comment
|
|
|
19 @comment texinfo manual for @file{cc-mode.el} version 4
|
|
32
|
20 @comment manual version: 2.66
|
|
0
|
21 @comment generated from the original README file by Krishna Padmasola
|
|
|
22 @comment <krishna@earth-gw.njit.edu>
|
|
|
23 @comment
|
|
|
24 @comment Barry A. Warsaw <bwarsaw@cnri.reston.va.us>
|
|
32
|
25 @comment Last modification: 1997/03/07 23:36:14
|
|
0
|
26 @comment
|
|
|
27 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
28
|
|
|
29
|
|
|
30 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
31 @comment The following line inserts the copyright notice
|
|
|
32 @comment into the Info file.
|
|
|
33 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
34
|
|
|
35 @ifinfo
|
|
2
|
36 Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.
|
|
0
|
37 @end ifinfo
|
|
|
38
|
|
|
39 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
40 @comment !!!The titlepage section does not appear in the Info file.!!!
|
|
|
41 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
42
|
|
|
43 @titlepage
|
|
|
44 @sp 10
|
|
|
45
|
|
|
46
|
|
|
47 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
48 @comment The title is printed in a large font.
|
|
|
49 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
50
|
|
32
|
51 @center @titlefont{CC Mode Version 4}
|
|
0
|
52 @sp 2
|
|
2
|
53 @center A GNU Emacs mode for editing C, C++, Objective-C, and Java code.
|
|
32
|
54 @center (manual revision: 2.66)
|
|
0
|
55 @sp 2
|
|
|
56 @center Barry A. Warsaw
|
|
|
57
|
|
|
58
|
|
|
59 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
60 @comment The following two commands start the copyright page
|
|
|
61 @comment for the printed manual. This will not appear in the Info file.
|
|
|
62 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
63
|
|
|
64 @page
|
|
|
65 @vskip 0pt plus 1filll
|
|
|
66 Copyright @copyright{} 1995 Free Software Foundation, Inc.
|
|
|
67 @end titlepage
|
|
|
68
|
|
|
69
|
|
|
70 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
71 @comment The Top node contains the master menu for the Info file.
|
|
|
72 @comment This appears only in the Info file, not the printed manual.
|
|
|
73 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
74
|
|
|
75 @node Top, Introduction, (dir), (dir)
|
|
|
76 @comment node-name, next, previous, up
|
|
|
77
|
|
|
78
|
|
|
79 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
80 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
81
|
|
|
82 @menu
|
|
|
83 * Introduction::
|
|
|
84 * Getting Connected::
|
|
|
85 * New Indentation Engine::
|
|
|
86 * Minor Modes::
|
|
2
|
87 * Commands::
|
|
0
|
88 * Customizing Indentation::
|
|
|
89 * Syntactic Symbols::
|
|
|
90 * Performance Issues::
|
|
|
91 * Frequently Asked Questions::
|
|
32
|
92 * Getting the latest CC Mode release::
|
|
0
|
93 * Sample .emacs File::
|
|
|
94 * Limitations and Known Bugs::
|
|
|
95 * Mailing Lists and Submitting Bug Reports::
|
|
|
96 * Concept Index::
|
|
|
97 * Command Index:: Command Index
|
|
|
98 * Key Index:: Key Index
|
|
|
99 * Variable Index:: Variable Index
|
|
|
100 @end menu
|
|
|
101
|
|
|
102 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
103 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
104
|
|
|
105 @node Introduction, Getting Connected, Top, Top
|
|
|
106 @comment node-name, next, previous, up
|
|
|
107 @chapter Introduction
|
|
|
108 @cindex Introduction
|
|
|
109
|
|
32
|
110 @macro ccmode
|
|
|
111 CC Mode
|
|
|
112 @end macro
|
|
|
113
|
|
0
|
114 @cindex BOCM
|
|
32
|
115 Welcome to @ccmode{}, version 4. This is a GNU Emacs mode for
|
|
0
|
116 editing files containing C, C++, Objective-C, and Java code.
|
|
|
117 This incarnation of the mode is descendant from @file{c-mode.el} (also
|
|
|
118 called "Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el}
|
|
32
|
119 version 2, which I have been maintaining since 1992. @ccmode{}
|
|
0
|
120 represents a significant milestone in the mode's life. It has been
|
|
|
121 fully merged back with Emacs 19's @file{c-mode.el}. Also a new, more
|
|
|
122 intuitive and flexible mechanism for controlling indentation has been
|
|
|
123 developed.
|
|
|
124
|
|
32
|
125 @ccmode{} version 4 supports the editing of K&R and ANSI C, @dfn{ARM}
|
|
|
126 @footnote{``The Annotated C++ Reference Manual'', by Ellis and
|
|
|
127 Stroustrup.} C++, Objective-C, and Java files. In this way, you can
|
|
|
128 easily set up consistent coding styles for use in editing all C, C++,
|
|
|
129 Objective-C, and Java programs. @ccmode{} does @emph{not} handle
|
|
|
130 font-locking (a.k.a. syntax coloring, keyword highlighting) or anything
|
|
|
131 of that nature, for any of the 4 modes. Those are handled by other
|
|
|
132 Emacs packages.
|
|
0
|
133
|
|
|
134 This manual will describe the following:
|
|
|
135
|
|
|
136 @itemize @bullet
|
|
|
137 @item
|
|
32
|
138 How to get started using @ccmode{}.
|
|
0
|
139
|
|
|
140 @item
|
|
|
141 How the new indentation engine works.
|
|
|
142
|
|
|
143 @item
|
|
|
144 How to customize the new indentation engine.
|
|
|
145
|
|
|
146 @end itemize
|
|
|
147
|
|
32
|
148 Note that the name of this package is ``@ccmode{}''. The main file for
|
|
|
149 @ccmode{} is @file{cc-mode.el}, but other files are included in the
|
|
|
150 @ccmode{} distribution. There is no top level @code{cc-mode} entry
|
|
|
151 point. All of the variables, commands, and functions in @ccmode{} are
|
|
|
152 prefixed with @code{c-@var{<thing>}}, and @code{c-mode},
|
|
|
153 @code{c++-mode}, @code{objc-mode}, and @code{java-mode} entry points are
|
|
|
154 provided. This file is intended to be a replacement for
|
|
|
155 @file{c-mode.el} and @file{c++-mode.el}.
|
|
0
|
156
|
|
|
157 @findex c-version
|
|
|
158 The major version number was incremented to 4 with the addition of
|
|
|
159 @code{objc-mode}. To find the minor revision number of this release, use
|
|
2
|
160 @kbd{M-x c-version RET}.
|
|
|
161
|
|
32
|
162 As of this writing (27-Feb-1997), Emacs 19.34, XEmacs 19.14, and XEmacs
|
|
|
163 20.0 are all distributed with @ccmode{}, but they may not have the
|
|
|
164 latest releases. You may therefore, want to upgrade your copy of
|
|
|
165 @ccmode{}. See @ref{Getting the latest CC Mode release}.
|
|
0
|
166
|
|
|
167 @cindex @file{cc-compat.el} file
|
|
2
|
168 This distribution also contains a file called @file{cc-compat.el} which
|
|
32
|
169 should ease your transition from BOCM to @ccmode{}. It currently
|
|
2
|
170 comes unguaranteed and unsupported, but this may change for future
|
|
|
171 versions. If you have a BOCM configuration you are really happy with,
|
|
32
|
172 and want to postpone learning how to configure @ccmode{}, take a
|
|
2
|
173 look at that file. It maps BOCM configuration variables to
|
|
32
|
174 @ccmode{}'s new indentation model.
|
|
0
|
175
|
|
|
176 A special word of thanks goes to Krishna Padmasola for his work in
|
|
|
177 converting the original @file{README} file to texinfo format.
|
|
|
178
|
|
|
179
|
|
|
180 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
181
|
|
|
182 @node Getting Connected, New Indentation Engine, Introduction, Top
|
|
|
183 @comment node-name, next, previous, up
|
|
|
184 @chapter Getting Connected
|
|
|
185 @cindex Getting Connected
|
|
|
186
|
|
|
187 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
188
|
|
32
|
189 @file{cc-mode.el} works well with the three main branches of Emacs:
|
|
|
190 XEmacs 19 and XEmacs 20, both maintained by @code{xemacs.org}, and Emacs
|
|
|
191 19 maintained by the Free Software Foundation. Emacs users will want to
|
|
|
192 use version 19.21 or better, XEmacs users will want 19.6 or better.
|
|
|
193 Earlier versions of these Emacsen have deficiencies and/or bugs which
|
|
|
194 will adversely affect the performance and usability of @ccmode{}. You
|
|
2
|
195 are better off just getting the latest version of Emacs or XEmacs.
|
|
0
|
196
|
|
|
197 @cindex @file{cc-mode-18.el} file
|
|
2
|
198 @file{cc-mode.el} will work with Emacs 18 if you use the
|
|
|
199 @file{cc-mode-18.el} compatibility file, but only moderately well. A
|
|
0
|
200 word of warning though, @emph{Emacs 18 lacks some fundamental
|
|
2
|
201 functionality and ultimately, using Emacs 18 is a losing
|
|
32
|
202 battle}. Hence @ccmode{} under Emacs 18 is no longer supported and
|
|
0
|
203 it is highly recommended that you upgrade to Emacs 19. If you use
|
|
32
|
204 @ccmode{} under Emacs 18, you're on your own. With @ccmode{}
|
|
0
|
205 version 5, Emacs 18 support will be dropped altogether.
|
|
|
206
|
|
|
207 Note that as of XEmacs 19.13 and Emacs 19.30, your Emacs already comes
|
|
32
|
208 with @ccmode{} version 4 preconfigured for your use. You should be
|
|
2
|
209 able to safely skip the rest of the setup information in this chapter,
|
|
32
|
210 unless you want to install the latest version of @ccmode{} into one
|
|
2
|
211 of these Emacsen.
|
|
0
|
212
|
|
32
|
213 @cindex .emacs file
|
|
0
|
214 The first thing you will want to do is put @file{cc-mode.el} somewhere
|
|
|
215 on your @code{load-path} so Emacs can find it. Do a @kbd{C-h v
|
|
|
216 load-path RET} to see all the directories Emacs looks at when loading a
|
|
|
217 file. If none of these directories are appropriate, create a new
|
|
|
218 directory and add it to your @code{load-path}:
|
|
|
219
|
|
|
220 @noindent
|
|
|
221 @emph{[in the shell]}
|
|
|
222 @example
|
|
|
223 @group
|
|
|
224
|
|
|
225 % cd
|
|
|
226 % mkdir mylisp
|
|
|
227 % mv cc-mode.el mylisp
|
|
|
228 % cd mylisp
|
|
|
229
|
|
|
230 @end group
|
|
|
231 @end example
|
|
|
232
|
|
|
233 @noindent
|
|
|
234 @emph{[in your .emacs file add]}
|
|
|
235 @example
|
|
|
236
|
|
|
237 (setq load-path (cons "~/mylisp" load-path))
|
|
|
238
|
|
|
239 @end example
|
|
|
240
|
|
|
241 @cindex byte compile
|
|
|
242 Next you want to @dfn{byte compile} @file{cc-mode.el}. The mode uses a
|
|
|
243 lot of macros so if you don't byte compile it, things will be unbearably
|
|
|
244 slow. @emph{You can ignore all byte-compiler warnings!} They are the
|
|
|
245 result of the supporting different versions of Emacs, and none of the
|
|
|
246 warnings have any effect on operation. Let me say this again:
|
|
|
247 @strong{You really can ignore all byte-compiler warnings!}
|
|
|
248
|
|
|
249 Here's what to do to byte-compile the file [in emacs]:
|
|
|
250 @example
|
|
|
251
|
|
|
252 M-x byte-compile-file RET ~/mylisp/cc-mode.el RET
|
|
|
253
|
|
|
254 @end example
|
|
|
255
|
|
|
256 If you are running a version of Emacs or XEmacs that comes with
|
|
32
|
257 @ccmode{} by default, you can simply add the following to your
|
|
0
|
258 @file{.emacs} file in order to upgrade to the latest version of
|
|
32
|
259 @ccmode{}:
|
|
0
|
260 @example
|
|
|
261
|
|
|
262 (load "cc-mode")
|
|
|
263
|
|
|
264 @end example
|
|
|
265
|
|
|
266 Users of even older versions of Emacs 19, Emacs 18, or of the older
|
|
|
267 Lucid Emacs will probably be running an Emacs that has BOCM
|
|
|
268 @file{c-mode.el} and possible @file{c++-mode.el} pre-dumped. If your
|
|
|
269 Emacs is dumped with either of these files you first need to make Emacs
|
|
|
270 ``forget'' about those older modes.
|
|
|
271
|
|
|
272 If you can do a @kbd{C-h v c-mode-map RET} without getting an error, you
|
|
|
273 need to add these lines at the top of your @file{.emacs} file:
|
|
|
274 @example
|
|
|
275 @group
|
|
|
276
|
|
|
277 (fmakunbound 'c-mode)
|
|
|
278 (makunbound 'c-mode-map)
|
|
|
279 (fmakunbound 'c++-mode)
|
|
|
280 (makunbound 'c++-mode-map)
|
|
|
281 (makunbound 'c-style-alist)
|
|
|
282
|
|
|
283 @end group
|
|
|
284 @end example
|
|
|
285
|
|
|
286 After those lines you will want to add the following autoloads to your
|
|
32
|
287 @file{.emacs} file so that @ccmode{} gets loaded at the right time:
|
|
0
|
288 @example
|
|
|
289 @group
|
|
|
290
|
|
|
291 (autoload 'c++-mode "cc-mode" "C++ Editing Mode" t)
|
|
|
292 (autoload 'c-mode "cc-mode" "C Editing Mode" t)
|
|
|
293 (autoload 'objc-mode "cc-mode" "Objective-C Editing Mode" t)
|
|
|
294 (autoload 'java-mode "cc-mode" "Java Editing Mode" t)
|
|
|
295
|
|
|
296 @end group
|
|
|
297 @end example
|
|
|
298
|
|
32
|
299 Alternatively, if you want to make sure @ccmode{} is loaded when
|
|
2
|
300 Emacs starts up, you could use this line instead of the autoloads
|
|
0
|
301 above:
|
|
|
302 @example
|
|
|
303
|
|
|
304 (require 'cc-mode)
|
|
|
305
|
|
|
306 @end example
|
|
|
307
|
|
|
308 Next, you will want to set up Emacs so that it edits C files in
|
|
2
|
309 @code{c-mode}, C++ files in @code{c++-mode}, Objective-C files in
|
|
|
310 @code{objc-mode}, and Java files in @code{java-mode}. You should
|
|
|
311 add the following to your @file{.emacs} file, which assumes
|
|
|
312 you'll be editing @code{.h} and @code{.c} files as C, @code{.hh},
|
|
|
313 @code{.cc}, @code{.H}, and @code{.C} files as C++, @code{.m} files as
|
|
|
314 Objective-C, and @code{.java} files as Java code. YMMV:
|
|
0
|
315 @example
|
|
|
316 @group
|
|
|
317
|
|
|
318 (setq auto-mode-alist
|
|
|
319 (append
|
|
|
320 '(("\\.C$" . c++-mode)
|
|
|
321 ("\\.H$" . c++-mode)
|
|
|
322 ("\\.cc$" . c++-mode)
|
|
|
323 ("\\.hh$" . c++-mode)
|
|
|
324 ("\\.c$" . c-mode)
|
|
|
325 ("\\.h$" . c-mode)
|
|
|
326 ("\\.m$" . objc-mode)
|
|
|
327 ("\\.java$" . java-mode)
|
|
|
328 ) auto-mode-alist))
|
|
|
329
|
|
|
330 @end group
|
|
|
331 @end example
|
|
|
332
|
|
|
333 You may already have some or all of these settings on your
|
|
|
334 @code{auto-mode-alist}, but it won't hurt to put them on there again.
|
|
|
335
|
|
2
|
336 That's all you need --- I know, I know, it sounds like a lot @code{:-)},
|
|
0
|
337 but after you've done all this, you should only need to quit and restart
|
|
|
338 Emacs. The next time you visit a C, C++, Objective-C, or Java file you
|
|
32
|
339 should be using @ccmode{}. You can check this easily by hitting
|
|
|
340 @kbd{M-x c-version RET}; you should see this message in the echo area:
|
|
0
|
341 @example
|
|
|
342
|
|
32
|
343 Using CC Mode version 4.@var{xxx}
|
|
0
|
344
|
|
|
345 @end example
|
|
|
346
|
|
32
|
347 @noindent
|
|
|
348 where @var{xxx} is the latest minor release number.
|
|
|
349
|
|
|
350
|
|
0
|
351 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
352 @node New Indentation Engine, Minor Modes, Getting Connected, Top
|
|
32
|
353 @comment node-name, next, previous, up
|
|
0
|
354
|
|
|
355 @chapter New Indentation Engine
|
|
|
356 @cindex New Indentation Engine
|
|
|
357 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
358
|
|
32
|
359 @ccmode{} has a new indentation engine, providing a simplified, yet
|
|
|
360 flexible and general mechanism for customizing indentation. It separates
|
|
|
361 indentation calculation into two steps: first, @ccmode{} analyzes the
|
|
|
362 line of code being indented to determine the kind of language construct
|
|
|
363 it's looking at, then it applies user defined offsets to the current
|
|
|
364 line based on this analysis.
|
|
0
|
365
|
|
|
366 This section will briefly cover how indentation is calculated in
|
|
32
|
367 @ccmode{}. It is important to understand the indentation model
|
|
|
368 being used so that you will know how to customize @ccmode{} for
|
|
0
|
369 your personal coding style.
|
|
|
370
|
|
|
371 @menu
|
|
|
372 * Syntactic Analysis::
|
|
|
373 * Indentation Calculation::
|
|
|
374 @end menu
|
|
2
|
375
|
|
0
|
376
|
|
|
377 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
378 @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine
|
|
|
379 @comment node-name, next, previous,up
|
|
|
380 @section Syntactic Analysis
|
|
|
381 @cindex Syntactic Analysis
|
|
|
382 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
383
|
|
|
384 @vindex c-offsets-alist
|
|
|
385 @vindex offsets-alist (c-)
|
|
|
386 @cindex relative buffer position
|
|
|
387 @cindex syntactic symbol
|
|
|
388 @cindex syntactic component
|
|
|
389 @cindex syntactic component list
|
|
|
390 @cindex relative buffer position
|
|
32
|
391 The first thing @ccmode{} does when indenting a line of code, is to
|
|
0
|
392 analyze the line, determining the @dfn{syntactic component list} of the
|
|
|
393 construct on that line. A @dfn{syntactic component} consists of a pair
|
|
|
394 of information (in lisp parlance, a @emph{cons cell}), where the first
|
|
|
395 part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative
|
|
|
396 buffer position}. Syntactic symbols describe elements of C code
|
|
|
397 @footnote{or C++, Objective-C, or Java code. In general, for the rest
|
|
|
398 of this manual I'll use the term ``C code'' to refer to all the C-like
|
|
|
399 dialects, unless otherwise noted.}, e.g. @code{statement},
|
|
|
400 @code{substatement}, @code{class-open}, @code{class-close}, etc.
|
|
|
401 @xref{Syntactic Symbols}, for a complete list of currently recognized
|
|
|
402 syntactic symbols and their semantics. The variable
|
|
|
403 @code{c-offsets-alist} also contains the list of currently supported
|
|
|
404 syntactic symbols.
|
|
|
405
|
|
|
406 Conceptually, a line of C code is always indented relative to the
|
|
|
407 indentation of some line higher up in the buffer. This is represented
|
|
|
408 by the relative buffer position in the syntactic component.
|
|
|
409
|
|
32
|
410 Here is an example. Suppose we had the following code as the only thing
|
|
|
411 in a @code{c++-mode} buffer @footnote{The line numbers in this and
|
|
|
412 future examples don't actually appear in the buffer, of course!}:
|
|
0
|
413 @example
|
|
|
414 @group
|
|
|
415
|
|
|
416 1: void swap( int& a, int& b )
|
|
|
417 2: @{
|
|
|
418 3: int tmp = a;
|
|
|
419 4: a = b;
|
|
|
420 5: b = tmp;
|
|
|
421 6: @}
|
|
|
422
|
|
|
423 @end group
|
|
|
424 @end example
|
|
|
425
|
|
|
426 @kindex C-c C-s
|
|
|
427 @findex c-show-syntactic-information
|
|
|
428 @findex show-syntactic-information (c-)
|
|
|
429 We can use the command @kbd{C-c C-s}
|
|
|
430 (@code{c-show-syntactic-information}) to simply report what the
|
|
|
431 syntactic analysis is for the current line. Running this command on
|
|
2
|
432 line 4 this example, we'd see in the echo area@footnote{With a universal
|
|
|
433 argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the
|
|
|
434 buffer as a comment
|
|
|
435 on the current line.}:
|
|
0
|
436 @example
|
|
|
437
|
|
|
438 ((statement . 35))
|
|
|
439
|
|
|
440 @end example
|
|
|
441
|
|
|
442 This tells us that the line is a statement and it is indented relative
|
|
|
443 to buffer position 35, which happens to be the @samp{i} in @code{int} on
|
|
32
|
444 line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you
|
|
0
|
445 would see:
|
|
|
446 @example
|
|
|
447
|
|
|
448 ((defun-block-intro . 29))
|
|
|
449
|
|
|
450 @end example
|
|
|
451
|
|
|
452 This indicates that the @samp{int} line is the first statement in a top
|
|
|
453 level function block, and is indented relative to buffer position 29,
|
|
|
454 which is the brace just after the function header.
|
|
|
455
|
|
|
456 Here's another example:
|
|
|
457 @example
|
|
|
458 @group
|
|
|
459
|
|
|
460 1: int add( int val, int incr, int doit )
|
|
|
461 2: @{
|
|
|
462 3: if( doit )
|
|
|
463 4: @{
|
|
|
464 5: return( val + incr );
|
|
|
465 6: @}
|
|
|
466 7: return( val );
|
|
|
467 8: @}
|
|
|
468
|
|
|
469 @end group
|
|
|
470 @end example
|
|
|
471
|
|
|
472 @noindent
|
|
|
473 Hitting @kbd{C-c C-s} on line 4 gives us:
|
|
|
474 @example
|
|
|
475
|
|
|
476 ((substatement-open . 46))
|
|
|
477
|
|
|
478 @end example
|
|
|
479
|
|
|
480 @cindex substatement
|
|
|
481 @cindex substatment block
|
|
|
482 @noindent
|
|
|
483 which tells us that this is a brace that @emph{opens} a substatement
|
|
32
|
484 block. @footnote{A @dfn{substatement} indicates the line after a
|
|
|
485 conditional statement, such as @code{if}, @code{else}, @code{while},
|
|
|
486 @code{do}, @code{switch}, or @code{for} in C. A @dfn{substatement
|
|
|
487 block} is a brace block following one of those conditionals.}
|
|
0
|
488
|
|
|
489 @cindex comment only line
|
|
|
490 Syntactic component lists can contain more than one component, and
|
|
|
491 individual syntactic components need not have relative buffer positions.
|
|
|
492 The most common example of this is a line that contains a @dfn{comment
|
|
|
493 only line}.
|
|
|
494 @example
|
|
|
495 @group
|
|
|
496
|
|
|
497 1: void draw_list( List<Drawables>& drawables )
|
|
|
498 2: @{
|
|
|
499 3: // call the virtual draw() method on each element in list
|
|
|
500 4: for( int i=0; i < drawables.count(), ++i )
|
|
|
501 5: @{
|
|
|
502 6: drawables[i].draw();
|
|
|
503 7: @}
|
|
|
504 8: @}
|
|
|
505
|
|
|
506 @end group
|
|
|
507 @end example
|
|
|
508
|
|
|
509 @noindent
|
|
2
|
510 Hitting @kbd{C-c C-s} on line 3 of this example gives:
|
|
0
|
511 @example
|
|
|
512
|
|
|
513 ((comment-intro) (defun-block-intro . 46))
|
|
|
514
|
|
|
515 @end example
|
|
|
516
|
|
|
517 @noindent
|
|
2
|
518 and you can see that the syntactic component list contains two syntactic
|
|
0
|
519 components. Also notice that the first component,
|
|
|
520 @samp{(comment-intro)} has no relative buffer position.
|
|
|
521
|
|
|
522
|
|
|
523 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
524 @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
|
|
|
525 @comment node-name, next, previous,up
|
|
|
526 @section Indentation Calculation
|
|
|
527 @cindex Indentation Calculation
|
|
|
528 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
529
|
|
|
530 @vindex c-offsets-alist
|
|
|
531 @vindex offsets-alist (c-)
|
|
|
532 Indentation for the current line is calculated using the syntactic
|
|
|
533 component list derived in step 1 above (see @ref{Syntactic Analysis}).
|
|
|
534 Each component contributes to the final total indentation of the line in
|
|
|
535 two ways.
|
|
|
536
|
|
|
537 First, the syntactic symbols are looked up in the @code{c-offsets-alist}
|
|
|
538 variable, which is an association list of syntactic symbols and the
|
|
2
|
539 offsets to apply for those symbols. These offsets are added to a
|
|
0
|
540 running total.
|
|
|
541
|
|
32
|
542 Second, if the component has a relative buffer position, @ccmode{}
|
|
0
|
543 adds the column number of that position to the running total. By adding
|
|
|
544 up the offsets and columns for every syntactic component on the list,
|
|
|
545 the final total indentation for the current line is computed.
|
|
|
546
|
|
|
547 Let's use our two code examples above to see how this works. Here is
|
|
|
548 our first example again:
|
|
|
549 @example
|
|
|
550 @group
|
|
|
551
|
|
|
552 1: void swap( int& a, int& b )
|
|
|
553 2: @{
|
|
|
554 3: int tmp = a;
|
|
|
555 4: a = b;
|
|
|
556 5: b = tmp;
|
|
|
557 6: @}
|
|
|
558
|
|
|
559 @end group
|
|
|
560 @end example
|
|
|
561
|
|
|
562 @kindex TAB
|
|
32
|
563 Let's say point is on line 3 and we hit the @key{TAB} key to re-indent
|
|
0
|
564 the line. Remember that the syntactic component list for that
|
|
|
565 line is:
|
|
|
566 @example
|
|
|
567
|
|
|
568 ((defun-block-intro . 29))
|
|
|
569
|
|
|
570 @end example
|
|
|
571
|
|
|
572 @noindent
|
|
32
|
573 @ccmode{} looks up @code{defun-block-intro} in the
|
|
0
|
574 @code{c-offsets-alist} variable. Let's say it finds the value @samp{4};
|
|
|
575 it adds this to the running total (initialized to zero), yielding a
|
|
|
576 running total indentation of 4 spaces.
|
|
|
577
|
|
32
|
578 Next @ccmode{} goes to buffer position 29 and asks for the current
|
|
|
579 column. This brace is in column zero, so @ccmode{}
|
|
0
|
580 adds @samp{0} to the running total. Since there is only one syntactic
|
|
|
581 component on the list for this line, indentation calculation is
|
|
|
582 complete, and the total indentation for the line
|
|
|
583 is 4 spaces.
|
|
|
584
|
|
|
585 Here's another example:
|
|
|
586 @example
|
|
|
587 @group
|
|
|
588
|
|
|
589 1: int add( int val, int incr, int doit )
|
|
|
590 2: @{
|
|
|
591 3: if( doit )
|
|
|
592 4: @{
|
|
|
593 5: return( val + incr );
|
|
|
594 6: @}
|
|
|
595 7: return( val );
|
|
|
596 8: @}
|
|
|
597
|
|
|
598 @end group
|
|
|
599 @end example
|
|
|
600
|
|
|
601 If we were to hit @kbd{TAB} on line 4 in the above example, the same
|
|
|
602 basic process is performed, despite the differences in the syntactic
|
|
|
603 component list. Remember that the list for this line is:
|
|
|
604 @example
|
|
|
605
|
|
|
606 ((substatement-open . 46))
|
|
|
607
|
|
|
608 @end example
|
|
|
609
|
|
32
|
610 Here, @ccmode{} first looks up the @code{substatement-open} symbol
|
|
0
|
611 in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This
|
|
32
|
612 yields a running total of 4. @ccmode{} then goes to
|
|
0
|
613 buffer position 46, which is the @samp{i} in @code{if} on line 3. This
|
|
|
614 character is in the fourth column on that line so adding this to the
|
|
|
615 running total yields an indentation for the line of 8 spaces.
|
|
|
616
|
|
|
617 Simple, huh?
|
|
|
618
|
|
|
619 Actually, the mode usually just does The Right Thing without you having
|
|
|
620 to think about it in this much detail. But when customizing
|
|
|
621 indentation, it's helpful to understand the general indentation model
|
|
|
622 being used.
|
|
|
623
|
|
|
624 @vindex c-echo-syntactic-information-p
|
|
|
625 @vindex echo-syntactic-information-p (c-)
|
|
|
626 @cindex TAB
|
|
32
|
627 As you configure @ccmode{}, you might want to set the variable
|
|
0
|
628 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
|
|
|
629 syntactic component list and calculated offset will always be echoed in
|
|
|
630 the minibuffer when you hit @kbd{TAB}.
|
|
|
631
|
|
|
632
|
|
|
633 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
2
|
634 @node Minor Modes, Commands, New Indentation Engine, Top
|
|
0
|
635 @comment node-name, next, previous,up
|
|
|
636
|
|
|
637 @chapter Minor Modes
|
|
|
638 @cindex Minor Modes
|
|
|
639 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
640
|
|
32
|
641 @ccmode{} contains two minor-mode-like features that you should
|
|
0
|
642 find useful while you enter new C code. The first is called
|
|
|
643 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
|
|
|
644 mode. These minor modes can be toggled on and off independently, and
|
|
32
|
645 @ccmode{} can be configured so that it starts up with any
|
|
0
|
646 combination of these minor modes. By default, both of these minor modes
|
|
|
647 are turned off.
|
|
|
648
|
|
|
649 The state of the minor modes is always reflected in the minor mode list
|
|
32
|
650 on the modeline of the @ccmode{} buffer. When auto-newline mode is
|
|
0
|
651 enabled, you will see @samp{C/a} on the mode line @footnote{Remember
|
|
2
|
652 that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC}, or
|
|
|
653 @samp{Java}.}. When hungry delete mode is enabled you would see
|
|
|
654 @samp{C/h} and when both modes are enabled, you'd see @samp{C/ah}.
|
|
0
|
655
|
|
|
656 @kindex C-c C-a
|
|
|
657 @kindex C-c C-d
|
|
|
658 @kindex C-c C-t
|
|
|
659 @findex c-toggle-hungry-state
|
|
|
660 @findex c-toggle-auto-state
|
|
|
661 @findex c-toggle-auto-hungry-state
|
|
|
662 @findex toggle-hungry-state (c-)
|
|
|
663 @findex toggle-auto-state (c-)
|
|
|
664 @findex toggle-auto-hungry-state (c-)
|
|
32
|
665 @ccmode{} provides keybindings which allow you to toggle the minor
|
|
2
|
666 modes on the fly while editing code. To toggle just the auto-newline
|
|
0
|
667 state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do
|
|
|
668 this, you should see the @samp{a} indicator either appear or disappear
|
|
|
669 on the modeline. Similarly, to toggle just the hungry-delete state, use
|
|
2
|
670 @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states,
|
|
|
671 use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
|
|
0
|
672
|
|
|
673 To set up the auto-newline and hungry-delete states to your preferred
|
|
|
674 values, you would need to add some lisp to your @file{.emacs} file that
|
|
|
675 called one of the @code{c-toggle-*-state} functions directly. When
|
|
|
676 called programmatically, each function takes a numeric value, where
|
|
|
677 a positive number enables the minor mode, a negative number disables the
|
|
|
678 mode, and zero toggles the current state of the mode.
|
|
|
679
|
|
|
680 So for example, if you wanted to enable both auto-newline and
|
|
|
681 hungry-delete for all your C file editing, you could add the following
|
|
|
682 to your @file{.emacs} file:
|
|
|
683 @example
|
|
|
684
|
|
32
|
685 (add-hook 'c-mode-common-hook
|
|
|
686 '(lambda () (c-toggle-auto-hungry-state 1)))
|
|
0
|
687
|
|
|
688 @end example
|
|
|
689
|
|
|
690
|
|
|
691 @cindex electric characters
|
|
|
692
|
|
|
693 @menu
|
|
|
694 * Auto-newline insertion::
|
|
|
695 * Hungry-deletion of whitespace::
|
|
|
696 @end menu
|
|
|
697
|
|
|
698 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
699 @node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes
|
|
|
700 @comment node-name, next, previous,up
|
|
|
701
|
|
|
702 @section Auto-newline insertion
|
|
|
703 @cindex Auto-newline insertion
|
|
|
704 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
705
|
|
|
706 @cindex electric commands
|
|
|
707 Auto-newline minor mode works by enabling certain @dfn{electric
|
|
|
708 commands}. Electric commands are typically bound to special characters
|
|
|
709 such as the left and right braces, colons, semi-colons, etc., which when
|
|
|
710 typed, perform some magic formatting in addition to inserting the typed
|
|
|
711 character. As a general rule, electric commands are only electric when
|
|
|
712 the following conditions apply:
|
|
|
713
|
|
|
714 @itemize @bullet
|
|
|
715 @item
|
|
|
716 Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
|
|
|
717 @samp{C/ah} indicator on the modeline.
|
|
|
718
|
|
|
719 @cindex literal
|
|
|
720 @cindex syntactic whitespace
|
|
|
721 @item
|
|
|
722 The character was not typed inside of a literal @footnote{A
|
|
32
|
723 @dfn{literal} is defined as any comment, string, or cpp macro
|
|
|
724 definition. These constructs are also known as @dfn{syntactic
|
|
|
725 whitespace} since they are usually ignored when scanning C code.}.
|
|
0
|
726
|
|
|
727 @item
|
|
|
728 @kindex C-u
|
|
|
729 No numeric argument was supplied to the command (i.e. it was typed as
|
|
|
730 normal, with no @kbd{C-u} prefix).
|
|
|
731
|
|
|
732 @end itemize
|
|
|
733
|
|
32
|
734 @findex c-enable-//-in-c-mode
|
|
|
735 @findex enable-//-in-c-mode (c-)
|
|
|
736 Some characters are electric in some languages, and not in others. For
|
|
0
|
737 example, the second slash (@kbd{/}) of a C++ style line comment is
|
|
|
738 electric in @code{c++-mode}, @code{objc-mode}, and @code{java-mode}, but
|
|
32
|
739 not in @code{c-mode}@footnote{Ordinarily, @samp{//} does not introduce a
|
|
|
740 comment in @code{c-mode}. However, if you call the function
|
|
|
741 @code{c-enable-//-in-c-mode}, @code{c-mode} will recognize C++ style
|
|
|
742 line comments. Note however that this is a global change which will
|
|
|
743 affect all your @code{c-mode} buffers.}.
|
|
0
|
744
|
|
|
745
|
|
|
746 @menu
|
|
|
747 * Hanging Braces::
|
|
|
748 * Hanging Colons::
|
|
|
749 * Hanging Semi-colons and commas::
|
|
|
750 * Other electric commands::
|
|
|
751 * Clean-ups::
|
|
|
752 @end menu
|
|
|
753
|
|
|
754 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
755 @node Hanging Braces, Hanging Colons, , Auto-newline insertion
|
|
|
756 @comment node-name, next, previous,up
|
|
|
757
|
|
|
758 @subsection Hanging Braces
|
|
|
759 @cindex Hanging Braces
|
|
|
760 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
761
|
|
|
762 @findex c-electric-brace
|
|
|
763 @findex electric-brace (c-)
|
|
|
764 @vindex c-hanging-braces-alist
|
|
|
765 @vindex hanging-braces-alist (c-)
|
|
|
766 @vindex c-offsets-alist
|
|
|
767 @vindex offsets-alist (c-)
|
|
|
768 When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),
|
|
|
769 the electric command @code{c-electric-brace} gets run. This command has
|
|
|
770 two electric formatting behaviors. First, it will perform some
|
|
|
771 re-indentation of the line the brace was typed on, and second, it will
|
|
|
772 add various newlines before and/or after the typed brace.
|
|
|
773 Re-indentation occurs automatically whenever the electric behavior is
|
|
|
774 enabled. If the brace ends up on a line other than the one it was typed
|
|
2
|
775 on, then that line is also indented according to
|
|
0
|
776 @code{c-offsets-alist}.
|
|
|
777
|
|
|
778 @cindex class-open syntactic symbol
|
|
|
779 @cindex class-close syntactic symbol
|
|
|
780 @cindex defun-open syntactic symbol
|
|
|
781 @cindex defun-close syntactic symbol
|
|
|
782 @cindex inline-open syntactic symbol
|
|
|
783 @cindex inline-close syntactic symbol
|
|
|
784 @cindex brace-list-open syntactic symbol
|
|
|
785 @cindex brace-list-close syntactic symbol
|
|
|
786 @cindex brace-list-intro syntactic symbol
|
|
|
787 @cindex brace-list-entry syntactic symbol
|
|
|
788 @cindex block-open syntactic symbol
|
|
|
789 @cindex block-close syntactic symbol
|
|
|
790 @cindex substatement-open syntactic symbol
|
|
|
791 @cindex statement-case-open syntactic symbol
|
|
2
|
792 @cindex extern-lang-open syntactic symbol
|
|
|
793 @cindex extern-lang-close syntactic symbol
|
|
0
|
794
|
|
|
795 The insertion of newlines is controlled by the
|
|
|
796 @code{c-hanging-braces-alist} variable. This variable contains a
|
|
|
797 mapping between syntactic symbols related to braces, and a list of
|
|
|
798 places to insert a newline. The syntactic symbols that are useful for
|
|
|
799 this list are: @code{class-open}, @code{class-close}, @code{defun-open},
|
|
|
800 @code{defun-close}, @code{inline-open}, @code{inline-close},
|
|
|
801 @code{brace-list-open}, @code{brace-list-close},
|
|
|
802 @code{brace-list-intro}, @code{brace-list-entry}, @code{block-open},
|
|
2
|
803 @code{block-close}, @code{substatement-open},
|
|
|
804 @code{statement-case-open},
|
|
|
805 @code{extern-lang-open}, and @code{extern-lang-close}.
|
|
|
806 @xref{Syntactic Symbols} for a more
|
|
0
|
807 detailed description of these syntactic symbols.
|
|
|
808
|
|
|
809 @cindex custom indentation function
|
|
|
810 The value associated with each syntactic symbol in this association list
|
|
|
811 is called an @var{ACTION} which can be either a function or a list.
|
|
|
812 @xref{Custom Brace and Colon Hanging} for a more detailed discussion of
|
|
|
813 using a function as a brace hanging @var{ACTION}.
|
|
|
814
|
|
2
|
815 When the @var{ACTION} is a list, it can contain any combination of the
|
|
32
|
816 symbols @code{before} and @code{after}, directing @ccmode{} where to
|
|
0
|
817 put newlines in relationship to the brace being inserted. Thus, if the
|
|
|
818 list contains only the symbol @code{after}, then the brace is said to
|
|
|
819 @dfn{hang} on the right side of the line, as in:
|
|
|
820 @example
|
|
|
821 @group
|
|
|
822
|
|
|
823 // here, open braces always `hang'
|
|
|
824 void spam( int i ) @{
|
|
|
825 if( i == 7 ) @{
|
|
|
826 dosomething(i);
|
|
|
827 @}
|
|
|
828 @}
|
|
|
829
|
|
|
830
|
|
|
831 @end group
|
|
|
832 @end example
|
|
|
833
|
|
|
834 When the list contains both @code{after} and @code{before}, the braces
|
|
|
835 will appear on a line by themselves, as shown by the close braces in the
|
|
|
836 above example. The list can also be empty, in which case no newlines
|
|
|
837 are added either before or after the brace.
|
|
|
838
|
|
|
839 For example, the default value of @code{c-hanging-braces-alist} is:
|
|
|
840 @example
|
|
|
841 @group
|
|
|
842
|
|
|
843 (defvar c-hanging-braces-alist '((brace-list-open)
|
|
|
844 (substatement-open after)
|
|
2
|
845 (block-close . c-snug-do-while)
|
|
|
846 (extern-lang-open after)))
|
|
0
|
847
|
|
|
848 @end group
|
|
|
849 @end example
|
|
|
850
|
|
|
851 @noindent
|
|
|
852 which says that @code{brace-list-open} braces should both hang on the
|
|
|
853 right side, and allow subsequent text to follow on the same line as the
|
|
2
|
854 brace. Also, @code{substatement-open} and @code{extern-lang-open}
|
|
|
855 braces should hang on the right side, but subsequent text should follow
|
|
|
856 on the next line. Here, in the @code{block-close} entry, you also see
|
|
|
857 an example of using a function as an @var{ACTION}.
|
|
0
|
858
|
|
32
|
859 A word of caution: it is not a good idea to hang top-level construct
|
|
|
860 introducing braces, such as @code{class-open} or @code{defun-open}.
|
|
|
861 Emacs makes an assumption that such braces will always appear in column
|
|
|
862 zero, hanging such braces can introduce performance problems.
|
|
|
863 @xref{Performance Issues} for more information.
|
|
|
864
|
|
0
|
865
|
|
|
866 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
867 @node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion
|
|
|
868 @comment node-name, next, previous,up
|
|
|
869
|
|
|
870 @subsection Hanging Colons
|
|
|
871 @cindex Hanging Colons
|
|
|
872 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
873
|
|
|
874 @vindex hanging-colons-alist (c-)
|
|
|
875 @vindex c-hanging-colons-alist
|
|
|
876 Using a mechanism similar to brace hanging (see @ref{Hanging Braces}),
|
|
|
877 colons can also be made to hang using the variable
|
|
|
878 @code{c-hanging-colons-alist}. The syntactic symbols appropriate for
|
|
|
879 this assocation list are: @code{case-label}, @code{label},
|
|
|
880 @code{access-label}, @code{member-init-intro}, and @code{inher-intro}.
|
|
2
|
881 Note however, that for @code{c-hanging-colons-alist} @var{ACTION}s as
|
|
|
882 functions are not supported. See also @ref{Custom Brace and Colon
|
|
|
883 Hanging} for details.
|
|
0
|
884
|
|
|
885 @cindex clean-ups
|
|
|
886 In C++, double-colons are used as a scope operator but because these
|
|
|
887 colons always appear right next to each other, newlines before and after
|
|
|
888 them are controlled by a different mechanism, called @dfn{clean-ups} in
|
|
32
|
889 @ccmode{}. @xref{Clean-ups} for details.
|
|
0
|
890
|
|
|
891
|
|
|
892 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
893 @node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion
|
|
|
894 @comment node-name, next, previous,up
|
|
|
895
|
|
|
896 @subsection Hanging Semi-colons and commas
|
|
|
897 @cindex Hanging Semi-colons and commas
|
|
|
898 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
899
|
|
32
|
900 Semicolons and commas are also electric in @ccmode{}, but since
|
|
0
|
901 these characters do not correspond directly to syntactic symbols, a
|
|
|
902 different mechanism is used to determine whether newlines should be
|
|
|
903 automatically inserted after these characters. @xref{Customizing
|
|
|
904 Semi-colons and Commas} for details.
|
|
|
905
|
|
|
906
|
|
|
907 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
908 @node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion
|
|
|
909 @comment node-name, next, previous,up
|
|
|
910
|
|
|
911 @subsection Other electric commands
|
|
|
912 @cindex Other electric commands
|
|
|
913 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
914
|
|
|
915 @kindex #
|
|
|
916 @findex c-electric-pound
|
|
|
917 @vindex c-electric-pound-behavior
|
|
|
918 @findex electric-pound (c-)
|
|
|
919 @vindex electric-pound-behavior (c-)
|
|
|
920 @vindex c-offsets-alist
|
|
|
921 @vindex offsets-alist (c-)
|
|
2
|
922 A few other keys also provide electric behavior. For example
|
|
|
923 @kbd{#} (@code{c-electric-pound}) is electric when typed as
|
|
0
|
924 the first non-whitespace character on a line. In this case, the
|
|
|
925 variable @code{c-electric-pound-behavior} is consulted for the electric
|
|
|
926 behavior. This variable takes a list value, although the only element
|
|
|
927 currently defined is @code{alignleft}, which tells this command to force
|
|
|
928 the @samp{#} character into column zero. This is useful for entering
|
|
|
929 cpp macro definitions.
|
|
|
930
|
|
|
931 @findex c-electric-star
|
|
|
932 @findex c-electric-slash
|
|
|
933 @findex electric-star (c-)
|
|
|
934 @findex electric-slash (c-)
|
|
|
935 @cindex comment-only line
|
|
2
|
936 Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and
|
|
|
937 @code{c-electric-slash} respectively) are also electric under
|
|
0
|
938 certain circumstances. If a star is inserted as the second character of
|
|
|
939 a C style block comment on a @dfn{comment-only} line, then the comment
|
|
|
940 delimiter is indented as defined by @code{c-offsets-alist}. A
|
|
|
941 comment-only line is defined as a line which contains only a comment, as
|
|
|
942 in:
|
|
|
943 @example
|
|
|
944 @group
|
|
|
945
|
|
|
946 void spam( int i )
|
|
|
947 @{
|
|
|
948 // this is a comment-only line...
|
|
|
949 if( i == 7 ) // but this is not
|
|
|
950 @{
|
|
|
951 dosomething(i);
|
|
|
952 @}
|
|
|
953 @}
|
|
|
954
|
|
|
955 @end group
|
|
|
956 @end example
|
|
|
957
|
|
|
958 Likewise, if a slash is inserted as the second slash in a C++ style line
|
|
|
959 comment (also only on a comment-only line), then the line is indented as
|
|
|
960 defined by @code{c-offsets-alist}.
|
|
|
961
|
|
2
|
962 @findex c-electric-lt-gt
|
|
|
963 @findex electric-lt-gt (c-)
|
|
|
964 @kindex <
|
|
|
965 @kindex >
|
|
|
966 Less-than and greater-than signs (@code{c-electric-lt-gt}) are also
|
|
|
967 electric, but only in C++ mode. Hitting the second of two @kbd{<} or
|
|
|
968 @kbd{>} keys re-indents the line if it is a C++ style stream operator.
|
|
|
969
|
|
0
|
970
|
|
|
971 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
972 @node Clean-ups, , Other electric commands, Auto-newline insertion
|
|
|
973 @comment node-name, next, previous,up
|
|
|
974
|
|
|
975 @subsection Clean-ups
|
|
|
976 @cindex Clean-ups
|
|
|
977 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
978
|
|
|
979 @dfn{Clean-ups} are a mechanism complementary to colon and brace
|
|
|
980 hanging. On the surface, it would seem that clean-ups overlap the
|
|
|
981 functionality provided by the @code{c-hanging-*-alist} variables, and
|
|
|
982 similarly, clean-ups are only enabled when auto-newline minor mode is
|
|
|
983 enabled. Clean-ups are used however to adjust code ``after-the-fact'',
|
|
|
984 i.e. to eliminate some whitespace that isn't inserted by electric
|
|
|
985 commands, or whitespace that contains intervening constructs.
|
|
|
986
|
|
|
987 @cindex literal
|
|
32
|
988 You can configure @ccmode{}'s clean-ups by setting the variable
|
|
0
|
989 @code{c-cleanup-list}, which is a list of clean-up symbols. By default,
|
|
32
|
990 @ccmode{} cleans up only the @code{scope-operator} construct, which
|
|
0
|
991 is necessary for proper C++ support. Note that clean-ups are only
|
|
|
992 performed when the construct does not occur within a literal (see
|
|
|
993 @ref{Auto-newline insertion}), and when there is nothing but whitespace
|
|
|
994 appearing between the individual components of the construct.
|
|
|
995
|
|
|
996 @vindex c-cleanup-list
|
|
|
997 @vindex cleanup-list (c-)
|
|
32
|
998 There are currently only five specific constructs that @ccmode{}
|
|
0
|
999 can clean up, as indicated by these symbols:
|
|
|
1000
|
|
|
1001 @itemize @bullet
|
|
|
1002 @item
|
|
2
|
1003 @code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by
|
|
0
|
1004 placing the entire construct on a single line. Clean-up occurs when the
|
|
|
1005 open brace after the @samp{else} is typed. So for example, this:
|
|
|
1006 @example
|
|
|
1007 @group
|
|
|
1008
|
|
|
1009 void spam(int i)
|
|
|
1010 @{
|
|
|
1011 if( i==7 )
|
|
|
1012 @{
|
|
|
1013 dosomething();
|
|
|
1014 @}
|
|
|
1015 else
|
|
|
1016 @{
|
|
|
1017
|
|
|
1018 @end group
|
|
|
1019 @end example
|
|
|
1020 @noindent
|
|
|
1021 appears like this after the open brace is typed:
|
|
|
1022 @example
|
|
|
1023 @group
|
|
|
1024
|
|
|
1025 void spam(int i)
|
|
|
1026 @{
|
|
|
1027 if( i==7 ) @{
|
|
|
1028 dosomething();
|
|
|
1029 @} else @{
|
|
|
1030
|
|
|
1031 @end group
|
|
|
1032 @end example
|
|
|
1033
|
|
|
1034 @item
|
|
32
|
1035 @code{brace-elseif-brace} --- similar to the @code{brace-else-brace}
|
|
|
1036 clean-up, but cleans up @samp{@} else if (...)@{} constructs. For
|
|
|
1037 example:
|
|
|
1038 @example
|
|
|
1039 @group
|
|
|
1040
|
|
|
1041 void spam(int i)
|
|
|
1042 @{
|
|
|
1043 if( i==7 )
|
|
|
1044 @{
|
|
|
1045 dosomething();
|
|
|
1046 @}
|
|
|
1047 else if( i==3 ) @{
|
|
|
1048
|
|
|
1049 @end group
|
|
|
1050 @end example
|
|
|
1051 @noindent
|
|
|
1052 appears like this after the open brace is typed:
|
|
|
1053 @example
|
|
|
1054 @group
|
|
|
1055
|
|
|
1056 void spam(int i)
|
|
|
1057 @{
|
|
|
1058 if( i==7 ) @{
|
|
|
1059 dosomething();
|
|
|
1060 @} else if( i==3 ) @{
|
|
|
1061
|
|
|
1062 @end group
|
|
|
1063 @end example
|
|
|
1064
|
|
|
1065 @item
|
|
2
|
1066 @code{empty-defun-braces} --- cleans up braces following a top-level
|
|
0
|
1067 function or class definition that contains no body. Clean up occurs
|
|
|
1068 when the closing brace is typed. Thus the following:
|
|
|
1069 @example
|
|
|
1070 @group
|
|
|
1071
|
|
|
1072 class Spam
|
|
|
1073 @{
|
|
|
1074 @}
|
|
|
1075
|
|
|
1076 @end group
|
|
|
1077 @end example
|
|
|
1078 @noindent
|
|
|
1079 is transformed into this when the close brace is typed:
|
|
|
1080 @example
|
|
|
1081 @group
|
|
|
1082
|
|
|
1083 class Spam
|
|
|
1084 @{@}
|
|
|
1085
|
|
|
1086 @end group
|
|
|
1087 @end example
|
|
|
1088
|
|
|
1089 @item
|
|
2
|
1090 @code{defun-close-semi} --- cleans up the terminating semi-colon on
|
|
0
|
1091 top-level function or class definitions when they follow a close
|
|
|
1092 brace. Clean up occurs when the semi-colon is typed.
|
|
|
1093 So for example, the following:
|
|
|
1094 @example
|
|
|
1095 @group
|
|
|
1096
|
|
|
1097 class Spam
|
|
|
1098 @{
|
|
|
1099 @}
|
|
|
1100 ;
|
|
|
1101
|
|
|
1102 @end group
|
|
|
1103 @end example
|
|
|
1104 @noindent
|
|
|
1105 is transformed into this when the semi-colon is typed:
|
|
|
1106
|
|
|
1107 @example
|
|
|
1108 @group
|
|
|
1109
|
|
|
1110 class Spam
|
|
|
1111 @{
|
|
|
1112 @};
|
|
|
1113
|
|
|
1114 @end group
|
|
|
1115 @end example
|
|
|
1116
|
|
|
1117 @item
|
|
2
|
1118 @code{list-close-comma} --- cleans up commas following braces in array
|
|
0
|
1119 and aggregate initializers. Clean up occurs when the comma is typed.
|
|
|
1120
|
|
|
1121 @item
|
|
2
|
1122 @code{scope-operator} --- cleans up double colons which may designate a
|
|
0
|
1123 C++ scope operator split across multiple lines@footnote{Certain C++
|
|
|
1124 constructs introduce ambiguous situations, so @code{scope-operator}
|
|
|
1125 clean-ups may not always be correct. This usually only occurs when
|
|
|
1126 scoped identifiers appear in switch label tags.}. Clean up occurs when
|
|
|
1127 the second colon is typed. You will always want @code{scope-operator}
|
|
|
1128 in the @code{c-cleanup-list} when you are editing C++ code.
|
|
|
1129
|
|
|
1130 @end itemize
|
|
|
1131
|
|
|
1132
|
|
|
1133 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1134 @node Hungry-deletion of whitespace, , Auto-newline insertion, Minor Modes
|
|
|
1135 @comment node-name, next, previous,up
|
|
|
1136
|
|
|
1137 @section Hungry-deletion of whitespace
|
|
|
1138 @cindex Hungry-deletion of whitespace
|
|
|
1139 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1140
|
|
|
1141 Hungry deletion of whitespace, or as it more commonly called,
|
|
|
1142 @dfn{hungry-delete mode}, is a simple feature that some people find
|
|
|
1143 extremely useful. In fact, you might find yourself wanting
|
|
|
1144 hungry-delete in @strong{all} your editing modes!
|
|
|
1145
|
|
|
1146 @kindex DEL
|
|
|
1147 In a nutshell, when hungry-delete mode is enabled, hitting the @kbd{DEL}
|
|
|
1148 character will consume all preceding whitespace, including newlines and
|
|
|
1149 tabs. This can really cut down on the number of @kbd{DEL}'s you have to
|
|
|
1150 type if, for example you made a mistake on the preceding line.
|
|
|
1151
|
|
|
1152 @findex c-electric-delete
|
|
|
1153 @findex electric-delete (c-)
|
|
|
1154 @vindex c-delete-function
|
|
|
1155 @vindex delete-function (c-)
|
|
|
1156 @cindex literal
|
|
32
|
1157 By default, @ccmode{} actually runs the command
|
|
0
|
1158 @code{c-electric-delete} when you hit @kbd{DEL}. When this command is
|
|
|
1159 used to delete a single character (i.e. when it is called interactively
|
|
|
1160 with no numeric argument), it really runs the function contained in the
|
|
|
1161 variable @code{c-delete-function}. This function is called with a
|
|
|
1162 single argument, which is the number of characters to delete.
|
|
|
1163 @code{c-delete-function} is also called when the @kbd{DEL} key is typed
|
|
|
1164 inside a literal (see @ref{Auto-newline insertion}. Inside a literal,
|
|
|
1165 @code{c-electric-delete} is not electric, which is typical of all the
|
|
|
1166 so-called electric commands.
|
|
|
1167
|
|
|
1168
|
|
|
1169 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
2
|
1170 @node Commands, Customizing Indentation, Minor Modes, Top
|
|
0
|
1171 @comment node-name, next, previous,up
|
|
|
1172
|
|
2
|
1173 @chapter Commands
|
|
|
1174 @cindex Commands
|
|
|
1175 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1176
|
|
|
1177 @menu
|
|
|
1178 * Indentation Commands::
|
|
|
1179 * Other Commands::
|
|
|
1180 @end menu
|
|
|
1181
|
|
|
1182 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1183 @node Indentation Commands, Other Commands, , Commands
|
|
|
1184 @comment node-name, next, previous,up
|
|
|
1185
|
|
|
1186 @section Indentation Commands
|
|
0
|
1187 @cindex Indentation Commands
|
|
|
1188 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1189
|
|
|
1190 Various commands are provided which allow you to conveniently re-indent
|
|
2
|
1191 C constructs. There are several things to
|
|
0
|
1192 note about these indentation commands. First, when you
|
|
2
|
1193 change your programming style, either interactively or through some
|
|
0
|
1194 other means, your file does @emph{not} automatically get re-indented.
|
|
|
1195 When you change style parameters, you will typically need to reformat
|
|
|
1196 the line, expression, or buffer to see the effects of your changes.
|
|
|
1197
|
|
|
1198 @cindex c-hanging- functions
|
|
|
1199 @findex c-hanging-braces-alist
|
|
|
1200 @findex hanging-braces-alist (c-)
|
|
|
1201 Second, changing some variables have no effect on existing code, even
|
|
2
|
1202 when you do re-indent. For example, the @code{c-hanging-*} variables
|
|
32
|
1203 and @code{c-cleanup-list} only affect new code as it is typed in
|
|
|
1204 on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting
|
|
|
1205 the buffer will not adjust placement of braces already in the file.
|
|
0
|
1206
|
|
|
1207 @vindex c-progress-interval
|
|
|
1208 @vindex progress-interval (c-)
|
|
|
1209 Third, re-indenting large portions of code is currently rather
|
|
|
1210 inefficient. Improvements have been made since previous releases of
|
|
32
|
1211 @ccmode{}, and much more radical improvements are planned, but for now
|
|
|
1212 you need to be aware of this @footnote{In particular, I have had people
|
|
|
1213 complain about the speed with which @code{lex(1)} output is re-indented.
|
|
|
1214 Lex, yacc, and other code generators usually output some pretty
|
|
|
1215 perversely formatted code. @emph{Don't} try to indent this stuff!}.
|
|
|
1216 Some provision has been made to at least inform you as to the progress
|
|
|
1217 of the re-indentation. The variable @code{c-progress-interval} controls
|
|
|
1218 how often a progress message is displayed. Set this variable to
|
|
|
1219 @code{nil} to inhibit progress messages. Note that this feature only
|
|
|
1220 works with Emacs 19 and beyond.
|
|
0
|
1221
|
|
|
1222 Also, except as noted below, re-indentation is always driven by the
|
|
|
1223 same mechanisms that control on-the-fly indentation of code. @xref{New
|
|
|
1224 Indentation Engine} for details.
|
|
|
1225
|
|
|
1226 @findex c-indent-command
|
|
|
1227 @findex indent-command (c-)
|
|
|
1228 @vindex c-tab-always-indent
|
|
|
1229 @vindex tab-always-indent (c-)
|
|
|
1230 @kindex TAB
|
|
|
1231 @cindex literal
|
|
2
|
1232 @vindex indent-tabs-mode
|
|
|
1233 @vindex c-insert-tab-function
|
|
|
1234 @vindex insert-tab-function (c-)
|
|
|
1235 @findex tab-to-tab-stop
|
|
0
|
1236 To indent a single line of code, use @kbd{TAB}
|
|
|
1237 (@code{c-indent-command}). The behavior of this command is controlled
|
|
|
1238 by the variable @code{c-tab-always-indent}. When this variable is
|
|
|
1239 @code{t}, @kbd{TAB} always just indents the current line. When
|
|
32
|
1240 @code{nil}, the line is indented only if point is at the left margin, or
|
|
2
|
1241 on or before the first non-whitespace character on the line, otherwise
|
|
|
1242 @emph{something else happens}@footnote{Actually what happens is that the
|
|
32
|
1243 function stored in @code{c-insert-tab-function} is called.
|
|
2
|
1244 Normally this just inserts a real tab character, or the equivalent
|
|
|
1245 number of spaces, depending on the setting of the variable
|
|
|
1246 @code{indent-tabs-mode}. If you preferred, you could set
|
|
|
1247 @code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}.
|
|
|
1248 If the value of @code{c-tab-always-indent} is something other than
|
|
|
1249 @code{t} or @code{nil} (e.g. @code{'other}), then a real tab
|
|
|
1250 character@footnote{The caveat about @code{indent-tabs-mode} in the
|
|
32
|
1251 previous footnote also applies here.} is inserted only when point is
|
|
2
|
1252 inside a literal (see @ref{Auto-newline insertion}), otherwise the line
|
|
|
1253 is indented.
|
|
0
|
1254
|
|
|
1255 @kindex M-C-q
|
|
|
1256 @findex c-indent-exp
|
|
|
1257 @findex indent-exp (c-)
|
|
|
1258 To indent an entire balanced brace or parenthesis expression, use
|
|
32
|
1259 @kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on
|
|
0
|
1260 the opening brace or parenthesis of the expression you want to indent.
|
|
|
1261
|
|
|
1262 @kindex C-c C-q
|
|
|
1263 @findex c-indent-defun
|
|
|
1264 @findex indent-defun (c-)
|
|
|
1265 Another very convenient keystroke is @kbd{C-c C-q}
|
|
|
1266 (@code{c-indent-defun}) when re-indents the entire top-level function or
|
|
32
|
1267 class definition that encompases point. It leaves point at the
|
|
0
|
1268 same position within the buffer.
|
|
|
1269
|
|
|
1270 @kindex M-C-\
|
|
|
1271 @findex indent-region
|
|
|
1272 To indent any arbitrary region of code, use @kbd{M-C-\}
|
|
|
1273 (@code{indent-region}). This is a standard Emacs command, specially
|
|
32
|
1274 tailored for C code in a @ccmode{} buffer. Note that of course,
|
|
|
1275 point and mark must delineate the region you
|
|
0
|
1276 want to indent.
|
|
|
1277
|
|
|
1278 @kindex M-C-h
|
|
|
1279 @findex c-mark-function
|
|
|
1280 @findex mark-function (c-)
|
|
|
1281 While not strictly an indentation function, @kbd{M-C-h}
|
|
|
1282 (@code{c-mark-function}) is useful for marking the current top-level
|
|
|
1283 function or class definition as the current region.
|
|
|
1284
|
|
2
|
1285 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1286 @node Other Commands, , Indentation Commands, Commands
|
|
|
1287 @comment node-name, next, previous,up
|
|
|
1288
|
|
|
1289 @section Other Commands
|
|
|
1290 @cindex Other Commands
|
|
|
1291 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1292
|
|
32
|
1293 @ccmode{} contains other useful command for moving around in C
|
|
2
|
1294 code.
|
|
|
1295
|
|
|
1296 @table @code
|
|
|
1297 @item C-c C-u (c-up-conditional)
|
|
|
1298 @kindex C-c C-u
|
|
|
1299 @findex c-up-conditional
|
|
|
1300 @findex up-conditional (c-)
|
|
32
|
1301 Move point back to the containing preprocessor conditional, leaving the
|
|
|
1302 mark behind. A prefix argument acts as a repeat count. With a negative
|
|
|
1303 argument, move point forward to the end of the containing
|
|
2
|
1304 preprocessor conditional. When going backwards, @code{#elif} is treated
|
|
|
1305 like @code{#else} followed by @code{#if}. When going forwards,
|
|
|
1306 @code{#elif} is ignored.@refill
|
|
|
1307
|
|
|
1308 @item C-c C-p (c-backward-conditional)
|
|
|
1309 @kindex C-c C-p
|
|
|
1310 @findex c-backward-conditional
|
|
|
1311 @findex backward-conditional (c-)
|
|
32
|
1312 Move point back over a preprocessor conditional, leaving the mark
|
|
2
|
1313 behind. A prefix argument acts as a repeat count. With a negative
|
|
|
1314 argument, move forward.
|
|
|
1315
|
|
|
1316 @item C-c C-n (c-forward-conditional)
|
|
|
1317 @kindex C-c C-n
|
|
|
1318 @findex c-forward-conditional
|
|
|
1319 @findex forward-conditional (c-)
|
|
32
|
1320 Move point forward across a preprocessor conditional, leaving the mark
|
|
2
|
1321 behind. A prefix argument acts as a repeat count. With a negative
|
|
|
1322 argument, move backward.
|
|
|
1323
|
|
|
1324 @item M-a (c-beginning-of-statement)
|
|
|
1325 @kindex ESC a
|
|
|
1326 @findex c-beginning-of-statement
|
|
|
1327 @findex beginning-of-statement (c-)
|
|
32
|
1328 Move point to the beginning of the innermost C statement. If point is
|
|
2
|
1329 already at the beginning of a statement, it moves to the beginning of
|
|
|
1330 the preceding statement. With prefix argument @var{n}, move back
|
|
|
1331 @var{n} @minus{} 1 statements.
|
|
|
1332
|
|
32
|
1333 If point is within a string or comment, or at the end of a comment, this
|
|
|
1334 command moves by sentences instead of statements.
|
|
|
1335
|
|
|
1336 When called from a program, this function takes three optional
|
|
|
1337 arguments: the numeric prefix argument, a buffer position limit (don't
|
|
|
1338 move back before that place), and a flag to indicate whether movement
|
|
|
1339 should be by statements (if @code{t}) or sentence (if non-@code{nil}).
|
|
2
|
1340
|
|
|
1341 @item M-e (c-end-of-statement)
|
|
|
1342 @kindex ESC e
|
|
|
1343 @findex c-end-of-statement
|
|
|
1344 @findex end-of-statement (c-)
|
|
32
|
1345 Move point to the end of the innermost C statement. If point is at the
|
|
2
|
1346 end of a statement, move to the end of the next statement. With prefix
|
|
|
1347 argument @var{n}, move forward @var{n} @minus{} 1 statements.
|
|
|
1348
|
|
32
|
1349 If point is within a string or comment, or at the end of a comment, this
|
|
|
1350 command moves by sentences instead of statements.
|
|
|
1351
|
|
|
1352 When called from a program, this function takes three optional
|
|
|
1353 arguments: the numeric prefix argument, a buffer position limit (don't
|
|
|
1354 move back before that place), and a flag to indicate whether movement
|
|
|
1355 should be by statements (if @code{t}) or sentence (if non-@code{nil}).
|
|
2
|
1356
|
|
|
1357 @item M-x c-forward-into-nomenclature
|
|
|
1358 @findex c-forward-into-nomenclature
|
|
|
1359 @findex forward-into-nomenclature (c-)
|
|
|
1360 A popular programming style, especially for object-oriented languages
|
|
|
1361 such as C++ is to write symbols in a mixed case format, where the first
|
|
|
1362 letter of each word is capitalized, and not separated by underscores.
|
|
|
1363 E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
|
|
|
1364
|
|
32
|
1365 This command moves point forward to end of a C++ nomenclature
|
|
2
|
1366 section or word. With prefix argument @var{n}, move @var{n} times.
|
|
|
1367
|
|
|
1368 @item M-x c-backward-into-nomenclature
|
|
|
1369 @findex c-backward-into-nomenclature
|
|
|
1370 @findex backward-into-nomenclature (c-)
|
|
32
|
1371 Move point backward to beginning of a C++ nomenclature
|
|
2
|
1372 section or word. With prefix argument @var{n}, move @var{n} times. If
|
|
|
1373 @var{n} is negative, move forward.
|
|
|
1374
|
|
|
1375 @kindex C-c :
|
|
|
1376 @findex c-scope-operator
|
|
|
1377 @findex scope-operator (c-)
|
|
|
1378 @item C-c : (c-scope-operator)
|
|
|
1379 In C++, it is also sometimes desirable to insert the double-colon scope
|
|
|
1380 operator without performing the electric behavior of colon insertion.
|
|
|
1381 @kbd{C-c :} does just this.
|
|
|
1382
|
|
32
|
1383 @item M-q (fill-paragraph)
|
|
|
1384 @kindex ESC q
|
|
|
1385 @findex fill-paragraph
|
|
|
1386 @vindex c-hanging-comment-starter-p
|
|
|
1387 @vindex c-hanging-comment-ender-p
|
|
|
1388 @vindex hanging-comment-starter-p (c-)
|
|
|
1389 @vindex hanging-comment-ender-p (c-)
|
|
|
1390 The command is used to fill a block style (C) or line style (C++)
|
|
|
1391 comment, in much the same way that text in the various text modes can be
|
|
|
1392 filled. You should never attempt to fill non-comment code sections;
|
|
|
1393 you'll end up with garbage! Two variables control how C style block
|
|
|
1394 comments are filled, specifically how the comment start and end
|
|
|
1395 delimiters are handled.
|
|
|
1396
|
|
|
1397 The variable @code{c-hanging-comment-starter-p} controls whether comment
|
|
|
1398 start delimiters which appear on a line by themselves, end up on a line
|
|
|
1399 by themselves after the fill. When the value is @code{nil}, the comment
|
|
|
1400 starter will remain on its own line@footnote{It will not be placed on a
|
|
|
1401 separate line if it is not already on a separate line.}. Otherwise,
|
|
|
1402 text on the next line will be put on the same line as the comment
|
|
|
1403 starter. This is called @dfn{hanging} because the following text hangs
|
|
|
1404 on the line with the comment starter.
|
|
|
1405
|
|
|
1406 The variable @code{c-hanging-comment-ender-p} controls the analogous
|
|
|
1407 behavior for the block comment end delimiter. When the value is
|
|
|
1408 @code{nil}, the comment ender will remain on its own line after the
|
|
|
1409 file@footnote{The same caveat as above holds true.}. Otherwise, the
|
|
|
1410 comment end delimiter will be placed at the end of the previous line.
|
|
|
1411
|
|
2
|
1412 @end table
|
|
0
|
1413
|
|
|
1414 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
2
|
1415 @node Customizing Indentation, Syntactic Symbols, Commands, Top
|
|
0
|
1416 @comment node-name, next, previous,up
|
|
|
1417
|
|
|
1418 @chapter Customizing Indentation
|
|
|
1419 @cindex Customizing Indentation
|
|
|
1420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1421
|
|
32
|
1422 @vindex c-offsets-alist
|
|
|
1423 @vindex offsets-alist (c-)
|
|
0
|
1424 @cindex c-set-offset
|
|
|
1425 @cindex set-offset (c-)
|
|
32
|
1426 The variable @code{c-offsets-alist} contains the mappings between
|
|
|
1427 syntactic symbols and the offsets to apply for those symbols. You
|
|
|
1428 should never modify this variable directly though. Use the function
|
|
|
1429 @code{c-set-offset} instead (see below for details).
|
|
|
1430
|
|
0
|
1431 The @code{c-offsets-alist} variable is where you customize all your
|
|
|
1432 indentations. You simply need to decide what additional offset you want
|
|
|
1433 to add for every syntactic symbol. You can use the command @kbd{C-c
|
|
|
1434 C-o} (@code{c-set-offset}) as the way to set offsets, both interactively
|
|
|
1435 and from your mode hook. Also, you can set up @emph{styles} of
|
|
|
1436 indentation just like in BOCM. Most likely, you'll
|
|
|
1437 find one of the pre-defined styles will suit your needs, but if not,
|
|
|
1438 this section will describe how to set up basic editing configurations.
|
|
|
1439 @xref{Styles} for an explanation of how to set up named styles.
|
|
|
1440
|
|
|
1441 @cindex c-basic-offset
|
|
|
1442 @cindex basic-offset (c-)
|
|
|
1443 As mentioned previously, the variable @code{c-offsets-alist} is an
|
|
2
|
1444 association list of syntactic symbols and the offsets to be applied for
|
|
32
|
1445 those symbols. In fact, these offset values can be any of an integer, a
|
|
|
1446 function or lambda expression, a variable name, or one of the following
|
|
|
1447 symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or
|
|
|
1448 @code{/}. These symbols describe offset in multiples of the value of
|
|
|
1449 the variable @code{c-basic-offset}. By defining a style's indentation
|
|
|
1450 in terms of this fundamental variable, you can change the amount of
|
|
|
1451 whitespace given to an indentation level while leaving the same
|
|
|
1452 relationship between levels. Here are the values that the special
|
|
0
|
1453 symbols correspond to:
|
|
|
1454
|
|
2
|
1455 @table @code
|
|
|
1456
|
|
|
1457 @item +
|
|
|
1458 @code{c-basic-offset} times 1
|
|
|
1459 @item -
|
|
|
1460 @code{c-basic-offset} times -1
|
|
|
1461 @item ++
|
|
|
1462 @code{c-basic-offset} times 2
|
|
|
1463 @item --
|
|
|
1464 @code{c-basic-offset} times -2
|
|
|
1465 @item *
|
|
|
1466 @code{c-basic-offset} times 0.5
|
|
|
1467 @item /
|
|
|
1468 @code{c-basic-offset} times -0.5
|
|
|
1469
|
|
|
1470 @end table
|
|
0
|
1471
|
|
32
|
1472 @vindex c-style-variables-are-local-p
|
|
|
1473 @vindex style-variables-are-local-p (c-)
|
|
0
|
1474 @noindent
|
|
|
1475 So, for example, because most of the default offsets are defined in
|
|
|
1476 terms of @code{+}, @code{-}, and @code{0}, if you like the general
|
|
|
1477 indentation style, but you use 4 spaces instead of 2 spaces per level,
|
|
|
1478 you can probably achieve your style just by changing
|
|
|
1479 @code{c-basic-offset} like so (in your @file{.emacs} file)@footnote{The
|
|
|
1480 reason you need to use @code{setq-default} instead of @code{setq} is
|
|
32
|
1481 that @code{c-basic-offset} is a buffer local variable, as are most
|
|
|
1482 configuration variables. If you were to put this code in, e.g. your
|
|
|
1483 @code{c-mode-common-hook} function, you could use @code{setq}.
|
|
|
1484 Alternatively, you can keep these variables global by setting
|
|
|
1485 @code{c-style-variables-are-local-p} to @code{nil}, but you must do this
|
|
|
1486 before @code{cc-mode.el} is loaded into your Emacs session.}:
|
|
0
|
1487 @example
|
|
|
1488
|
|
|
1489 (setq-default c-basic-offset 4)
|
|
|
1490
|
|
|
1491 @end example
|
|
|
1492
|
|
|
1493 @noindent
|
|
|
1494 This would change
|
|
|
1495 @example
|
|
|
1496 @group
|
|
|
1497
|
|
|
1498 int add( int val, int incr, int doit )
|
|
|
1499 @{
|
|
2
|
1500 if( doit )
|
|
|
1501 @{
|
|
|
1502 return( val + incr );
|
|
|
1503 @}
|
|
|
1504 return( val );
|
|
|
1505 @}
|
|
|
1506
|
|
|
1507 @end group
|
|
|
1508 @end example
|
|
|
1509 @noindent
|
|
|
1510 to
|
|
|
1511 @example
|
|
|
1512 @group
|
|
|
1513
|
|
|
1514 int add( int val, int incr, int doit )
|
|
|
1515 @{
|
|
0
|
1516 if( doit )
|
|
|
1517 @{
|
|
|
1518 return( val + incr );
|
|
|
1519 @}
|
|
|
1520 return( val );
|
|
|
1521 @}
|
|
|
1522
|
|
|
1523 @end group
|
|
|
1524 @end example
|
|
|
1525
|
|
|
1526
|
|
|
1527 To change indentation styles more radically, you will want to change the
|
|
|
1528 value associated with the syntactic symbols in the
|
|
|
1529 @code{c-offsets-alist} variable. First, I'll show you how to do that
|
|
|
1530 interactively, then I'll describe how to make changes to your
|
|
|
1531 @file{.emacs} file so that your changes are more permanent.
|
|
|
1532
|
|
|
1533 @menu
|
|
|
1534 * Interactive Customization::
|
|
|
1535 * Permanent Customization::
|
|
|
1536 * Styles::
|
|
|
1537 * Advanced Customizations::
|
|
|
1538 @end menu
|
|
|
1539
|
|
|
1540 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1541 @node Interactive Customization, Permanent Customization, , Customizing Indentation
|
|
|
1542 @comment node-name, next, previous,up
|
|
|
1543
|
|
|
1544 @section Interactive Customization
|
|
|
1545 @cindex Interactive Customization
|
|
|
1546 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1547
|
|
|
1548 As an example of how to customize indentation, let's change the
|
|
2
|
1549 style of this example@footnote{In this an subsequent examples, the
|
|
|
1550 original code is formatted using the @samp{gnu} style unless otherwise
|
|
|
1551 indicated. @xref{Styles}.}:
|
|
0
|
1552 @example
|
|
|
1553 @group
|
|
|
1554
|
|
|
1555 1: int add( int val, int incr, int doit )
|
|
|
1556 2: @{
|
|
2
|
1557 3: if( doit )
|
|
|
1558 4: @{
|
|
|
1559 5: return( val + incr );
|
|
|
1560 6: @}
|
|
|
1561 7: return( val );
|
|
0
|
1562 8: @}
|
|
|
1563
|
|
|
1564 @end group
|
|
|
1565 @end example
|
|
|
1566 @noindent
|
|
|
1567 to:
|
|
|
1568 @example
|
|
|
1569 @group
|
|
|
1570
|
|
|
1571 1: int add( int val, int incr, int doit )
|
|
|
1572 2: @{
|
|
2
|
1573 3: if( doit )
|
|
|
1574 4: @{
|
|
|
1575 5: return( val + incr );
|
|
|
1576 6: @}
|
|
|
1577 7: return( val );
|
|
0
|
1578 8: @}
|
|
|
1579
|
|
|
1580 @end group
|
|
|
1581 @end example
|
|
|
1582
|
|
|
1583 In other words, we want to change the indentation of braces that open a
|
|
|
1584 block following a condition so that the braces line up under the
|
|
|
1585 conditional, instead of being indented. Notice that the construct we
|
|
|
1586 want to change starts on line 4. To change the indentation of a line,
|
|
2
|
1587 we need to see which syntactic components affect the offset calculations
|
|
0
|
1588 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
|
|
|
1589 @example
|
|
|
1590
|
|
2
|
1591 ((substatement-open . 44))
|
|
0
|
1592
|
|
|
1593 @end example
|
|
|
1594
|
|
|
1595 @findex c-set-offset
|
|
|
1596 @findex set-offset (c-)
|
|
|
1597 @kindex C-c C-o
|
|
|
1598 @noindent
|
|
|
1599 so we know that to change the offset of the open brace, we need to
|
|
|
1600 change the indentation for the @code{substatement-open} syntactic
|
|
|
1601 symbol. To do this interactively, just hit @kbd{C-c C-o}
|
|
|
1602 (@code{c-set-offset}). This prompts you for the syntactic symbol to
|
|
|
1603 change, providing a reasonable default. In this case, the default is
|
|
|
1604 @code{substatement-open}, which is just the syntactic symbol we want to
|
|
|
1605 change!
|
|
|
1606
|
|
32
|
1607 After you hit return, @ccmode{} will then prompt you for the new
|
|
0
|
1608 offset value, with the old value as the default. The default in this
|
|
2
|
1609 case is @samp{+}, but we want no extra indentation so enter
|
|
0
|
1610 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
|
|
|
1611 syntactic symbol @code{substatement-open} in the @code{c-offsets-alist}
|
|
|
1612 variable.
|
|
|
1613
|
|
|
1614 @findex c-indent-defun
|
|
|
1615 @findex indent-defun (c-)
|
|
|
1616 @kindex C-c C-q
|
|
|
1617 To check your changes quickly, just hit @kbd{C-c C-q}
|
|
|
1618 (@code{c-indent-defun}) to reindent the entire function. The example
|
|
|
1619 should now look like:
|
|
|
1620 @example
|
|
|
1621 @group
|
|
|
1622
|
|
|
1623 1: int add( int val, int incr, int doit )
|
|
|
1624 2: @{
|
|
2
|
1625 3: if( doit )
|
|
|
1626 4: @{
|
|
|
1627 5: return( val + incr );
|
|
|
1628 6: @}
|
|
|
1629 7: return( val );
|
|
0
|
1630 8: @}
|
|
|
1631
|
|
|
1632 @end group
|
|
|
1633 @end example
|
|
|
1634
|
|
|
1635 Notice how just changing the open brace offset on line 4 is all we
|
|
|
1636 needed to do. Since the other affected lines are indented relative to
|
|
|
1637 line 4, they are automatically indented the way you'd expect. For more
|
|
|
1638 complicated examples, this may not always work. The general approach to
|
|
|
1639 take is to always start adjusting offsets for lines higher up in the
|
|
|
1640 file, then re-indent and see if any following lines need further
|
|
|
1641 adjustments.
|
|
|
1642
|
|
|
1643 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1644 @node Permanent Customization, Styles, Interactive Customization, Customizing Indentation
|
|
|
1645 @comment node-name, next, previous,up
|
|
|
1646
|
|
32
|
1647 @section Permanent Customization
|
|
|
1648 @cindex Permanent Customization
|
|
0
|
1649 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1650
|
|
|
1651 @vindex c-mode-common-hook
|
|
|
1652 @vindex c-mode-hook
|
|
|
1653 @vindex c++-mode-hook
|
|
|
1654 @vindex objc-mode-hook
|
|
|
1655 @vindex java-mode-hook
|
|
|
1656 @cindex hooks
|
|
|
1657 To make this change permanent, you need to add some lisp code to your
|
|
32
|
1658 @file{.emacs} file. @ccmode{} provides several hooks that you can
|
|
2
|
1659 use to customize the mode according to your coding style. Each language
|
|
32
|
1660 mode has its own hook, adhering to standard Emacs major mode
|
|
2
|
1661 conventions. There is also one general hook:
|
|
|
1662
|
|
|
1663 @itemize @bullet
|
|
|
1664
|
|
|
1665 @item
|
|
|
1666 @code{c-mode-hook} --- for C buffers only
|
|
|
1667 @item
|
|
|
1668 @code{c++-mode-hook} --- for C++ buffers only
|
|
|
1669 @item
|
|
|
1670 @code{objc-mode-hook} --- for Objective-C buffers only
|
|
|
1671 @item
|
|
|
1672 @code{java-mode-hook} --- for Java buffers only
|
|
|
1673 @item
|
|
|
1674 @code{c-mode-common-hook} --- common across all languages
|
|
|
1675
|
|
|
1676 @end itemize
|
|
|
1677
|
|
|
1678 The language hooks get run as the last thing when you enter that
|
|
|
1679 language-specific mode. The @code{c-mode-common-hook} is run by all
|
|
|
1680 supported modes @emph{before} the language specific hook, and thus can
|
|
|
1681 contain customizations that are common across all languages. Most of
|
|
|
1682 the examples in this section will assume you are using the common
|
|
|
1683 hook@footnote{The interaction between @code{java-mode} and the hook
|
|
|
1684 variables is slightly different than for the other modes.
|
|
|
1685 @code{java-mode} sets the style (see @ref{Styles}) of the buffer to
|
|
|
1686 @samp{java} @emph{before} running the @code{c-mode-common-hook} or
|
|
|
1687 @code{java-mode-hook}. You need to be aware of this so any style
|
|
|
1688 settings in @code{c-mode-common-hook} doesn't clobber your Java style.}.
|
|
0
|
1689
|
|
|
1690 Here's a simplified example of what you can add to your @file{.emacs}
|
|
|
1691 file to make the changes described in the previous section
|
|
32
|
1692 (@ref{Interactive Customization}) more permanent. See the Emacs manuals
|
|
|
1693 for more information on customizing Emacs via hooks. @xref{Sample
|
|
|
1694 .emacs File} for a more complete sample @file{.emacs} file.
|
|
0
|
1695 @footnote{The use of @code{add-hook} in this example only works for
|
|
32
|
1696 Emacs 19 and beyond. Workarounds are available if you are using Emacs
|
|
|
1697 18.}
|
|
0
|
1698 @example
|
|
|
1699 @group
|
|
|
1700
|
|
|
1701 (defun my-c-mode-common-hook ()
|
|
|
1702 ;; my customizations for all of c-mode, c++-mode, objc-mode, java-mode
|
|
|
1703 (c-set-offset 'substatement-open 0)
|
|
|
1704 ;; other customizations can go here
|
|
|
1705 )
|
|
|
1706 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
1707
|
|
|
1708 @end group
|
|
|
1709 @end example
|
|
|
1710
|
|
|
1711 For complex customizations, you will probably want to set up a
|
|
|
1712 @emph{style} that groups all your customizations under a single
|
|
|
1713 name.
|
|
|
1714
|
|
|
1715 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1716 @node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
|
|
|
1717 @comment node-name, next, previous,up
|
|
|
1718
|
|
|
1719 @section Styles
|
|
|
1720 @cindex Styles
|
|
|
1721 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1722
|
|
|
1723 Most people only need to edit code formatted in just a few well-defined
|
|
|
1724 and consistent styles. For example, their organization might impose a
|
|
|
1725 ``blessed'' style that all its programmers must conform to. Similarly,
|
|
|
1726 people who work on GNU software will have to use the GNU coding style on
|
|
|
1727 C code. Some shops are more lenient, allowing some variety of coding
|
|
|
1728 styles, and as programmers come and go, there could be a number of
|
|
32
|
1729 styles in use. For this reason, @ccmode{} makes it convenient for
|
|
0
|
1730 you to set up logical groupings of customizations called @dfn{styles},
|
|
|
1731 associate a single name for any particular style, and pretty easily
|
|
2
|
1732 start editing new or existing code using these styles. This section
|
|
0
|
1733 describes how to set up styles and how to edit your C code using styles.
|
|
|
1734
|
|
|
1735 @menu
|
|
|
1736 * Built-in Styles::
|
|
|
1737 * Adding Styles::
|
|
|
1738 * File Styles::
|
|
|
1739 @end menu
|
|
|
1740
|
|
|
1741
|
|
|
1742 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1743 @node Built-in Styles, Adding Styles, , Styles
|
|
|
1744 @comment node-name, next, previous,up
|
|
|
1745
|
|
|
1746 @subsection Built-in Styles
|
|
|
1747 @cindex Built-in Styles
|
|
|
1748 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1749
|
|
32
|
1750 If you're lucky, one of @ccmode{}'s built-in styles might be just
|
|
|
1751 what you're looking for. These include:
|
|
0
|
1752
|
|
|
1753 @itemize @bullet
|
|
|
1754 @item
|
|
|
1755 @cindex GNU style
|
|
2
|
1756 @code{gnu} --- coding style blessed by the Free Software Foundation
|
|
0
|
1757 for C code in GNU programs.
|
|
|
1758
|
|
|
1759 @item
|
|
|
1760 @cindex K&R style
|
|
2
|
1761 @code{k&r} --- The classic Kernighan and Ritchie style for C code.
|
|
0
|
1762
|
|
|
1763 @item
|
|
|
1764 @cindex BSD style
|
|
2
|
1765 @code{bsd} --- Also known as ``Allman style'' after Eric Allman.
|
|
|
1766
|
|
|
1767 @item
|
|
|
1768 @cindex Whitesmith style
|
|
|
1769 @code{whitesmith} --- Popularized by the examples that came with
|
|
|
1770 Whitesmiths C, an early commercial C compiler.
|
|
0
|
1771
|
|
|
1772 @item
|
|
|
1773 @cindex Stroustrup style
|
|
2
|
1774 @code{stroustrup} --- The classic Stroustrup style for C++ code.
|
|
0
|
1775
|
|
|
1776 @item
|
|
|
1777 @cindex Ellemtel style
|
|
2
|
1778 @code{ellemtel} --- Popular C++ coding standards as defined by
|
|
0
|
1779 ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats
|
|
|
1780 Henricson, Ellemtel @footnote{This document is ftp'able from
|
|
|
1781 @code{euagate.eua.ericsson.se}}.
|
|
|
1782
|
|
|
1783 @item
|
|
32
|
1784 @cindex Linux style
|
|
|
1785 @code{linux} --- C coding standard for Linux development.
|
|
|
1786
|
|
|
1787 @item
|
|
|
1788 @cindex Python style
|
|
|
1789 @code{python} --- C coding standard for Python extension
|
|
|
1790 modules@footnote{Python is a high level scripting language with a C/C++
|
|
|
1791 foreign function interface. For more information, see
|
|
|
1792 @code{<http://www.python.org/>}.}.
|
|
|
1793
|
|
|
1794 @item
|
|
0
|
1795 @cindex Java style
|
|
|
1796 @cindex java-mode
|
|
2
|
1797 @code{java} --- The style for editing Java code. Note that this style is
|
|
0
|
1798 automatically installed when you enter @code{java-mode}.
|
|
|
1799
|
|
|
1800 @end itemize
|
|
|
1801
|
|
|
1802 @findex c-set-style
|
|
|
1803 @findex set-style (c-)
|
|
32
|
1804 @kindex C-c .
|
|
0
|
1805 If you'd like to experiment with these built-in styles you can simply
|
|
32
|
1806 type the following in a @ccmode{} buffer:
|
|
0
|
1807 @example
|
|
|
1808 @group
|
|
|
1809
|
|
32
|
1810 @kbd{C-c . @var{STYLE-NAME} RET}
|
|
0
|
1811
|
|
|
1812 @end group
|
|
|
1813 @end example
|
|
|
1814 @noindent
|
|
32
|
1815 @kbd{C-c .} runs the command @code{c-set-style}. Note that all style
|
|
|
1816 names are case insensitive, even the ones you define.
|
|
0
|
1817
|
|
|
1818 Setting a style in this way does @emph{not} automatically re-indent your
|
|
|
1819 file. For commands that you can use to view the effect of your changes,
|
|
2
|
1820 see @ref{Commands}.
|
|
0
|
1821
|
|
|
1822 Once you find a built-in style you like, you can make the change
|
|
32
|
1823 permanent by adding some lisp to your @file{.emacs} file. Let's say for
|
|
2
|
1824 example that you want to use the @samp{ellemtel} style in all your
|
|
0
|
1825 files. You would add this:
|
|
|
1826 @example
|
|
|
1827 @group
|
|
|
1828
|
|
|
1829 (defun my-c-mode-common-hook ()
|
|
2
|
1830 ;; use Ellemtel style for all C like languages
|
|
0
|
1831 (c-set-style "ellemtel")
|
|
|
1832 ;; other customizations can go here
|
|
|
1833 )
|
|
|
1834 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
1835
|
|
|
1836 @end group
|
|
|
1837 @end example
|
|
|
1838
|
|
32
|
1839 @cindex cc-mode style
|
|
2
|
1840 There is one other special style you can use, called @samp{cc-mode}
|
|
|
1841 style. This style is special because all other styles implicitly
|
|
|
1842 inherit from it; in other words, whenever you set a style,
|
|
|
1843 @samp{cc-mode} is applied before the one you selected. This means
|
|
|
1844 your style need only define the differences between it and
|
|
|
1845 @samp{cc-mode} style.
|
|
|
1846
|
|
32
|
1847 Note @emph{you should never change any of the default styles}.
|
|
|
1848 Instead, it's better to add a new style using @code{c-add-style}
|
|
|
1849 (@xref{Adding Styles}). This is especially true for @code{cc-mode} and
|
|
|
1850 @code{java} styles.
|
|
|
1851
|
|
|
1852 @vindex c-indentation-style
|
|
|
1853 @vindex indentation-style (c-)
|
|
2
|
1854 Note that for BOCM compatibility, @samp{gnu} is the default
|
|
|
1855 style, and any non-style based customizations you make (i.e. in
|
|
|
1856 @code{c-mode-common-hook} in your
|
|
|
1857 @file{.emacs} file) will be based on @samp{gnu} style unless you do
|
|
32
|
1858 a @code{c-set-style} as the first thing in your hook. The variable
|
|
|
1859 @code{c-indentation-style} always contains the buffer's current style name,
|
|
|
1860 as a string.
|
|
0
|
1861
|
|
|
1862
|
|
|
1863 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1864 @node Adding Styles, File Styles, Built-in Styles, Styles
|
|
|
1865 @comment node-name, next, previous,up
|
|
|
1866
|
|
|
1867 @subsection Adding Styles
|
|
|
1868 @cindex Adding Styles
|
|
|
1869 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1870
|
|
|
1871 @vindex c-style-alist
|
|
|
1872 @vindex style-alist (c-)
|
|
|
1873 @findex c-add-style
|
|
|
1874 @findex add-style (c-)
|
|
|
1875 If none of the built-in styles is appropriate, you'll probably want to
|
|
2
|
1876 add a new @dfn{style definition}. Styles are kept in the
|
|
|
1877 @code{c-style-alist} variable, but you should never modify this variable
|
|
32
|
1878 directly. Instead, @ccmode{} provides the function
|
|
2
|
1879 @code{c-add-style} that you can use to easily add new styles or change
|
|
|
1880 existing styles. This function takes two arguments, a @var{stylename}
|
|
|
1881 string, and an association list @var{description} of style
|
|
|
1882 customizations. If @var{stylename} is not already in
|
|
|
1883 @code{c-style-alist}, the new style is added, otherwise the style is
|
|
|
1884 changed to the new @var{description}.
|
|
|
1885 This function also takes an optional third argument, which if
|
|
|
1886 non-@code{nil}, automatically applies the new style to the current
|
|
|
1887 buffer.
|
|
0
|
1888
|
|
|
1889 The sample @file{.emacs} file provides a concrete example of how a new
|
|
|
1890 style can be added and automatically set. @xref{Sample .emacs File}.
|
|
|
1891
|
|
|
1892 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1893 @node File Styles, , Adding Styles, Styles
|
|
|
1894 @comment node-name, next, previous,up
|
|
|
1895
|
|
|
1896 @subsection File Styles
|
|
|
1897 @cindex File Styles
|
|
|
1898 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1899
|
|
|
1900 @cindex local variables
|
|
|
1901 The Emacs manual describes how you can customize certain variables on a
|
|
|
1902 per-file basis by including a @dfn{Local Variable} block at the end of
|
|
|
1903 the file. So far, you've only seen a functional interface to
|
|
32
|
1904 @ccmode{}, which is highly inconvenient for use in a Local Variable
|
|
|
1905 block. @ccmode{} provides two variables that make it easier for
|
|
0
|
1906 you to customize your style on a per-file basis.
|
|
|
1907
|
|
|
1908 @vindex c-file-style
|
|
|
1909 @vindex file-style (c-)
|
|
|
1910 @vindex c-file-offsets
|
|
|
1911 @vindex file-offsets (c-)
|
|
|
1912
|
|
2
|
1913 The variable @code{c-file-style} can be set to a style name string.
|
|
32
|
1914 When the file is visited, @ccmode{} will automatically set the
|
|
2
|
1915 file's style to this style using @code{c-set-style}.
|
|
0
|
1916
|
|
|
1917 @vindex c-offsets-alist
|
|
|
1918 @vindex offsets-alist (c-)
|
|
|
1919 @findex c-set-offset
|
|
|
1920 @findex set-offset (c-)
|
|
|
1921 Another variable, @code{c-file-offsets}, takes an association list
|
|
|
1922 similar to what is allowed in @code{c-offsets-alist}. When the file is
|
|
32
|
1923 visited, @ccmode{} will automatically institute these offets using
|
|
0
|
1924 @code{c-set-offset}.
|
|
|
1925
|
|
|
1926 Note that file style settings (i.e. @code{c-file-style}) are applied
|
|
2
|
1927 before file offset settings (i.e. @code{c-file-offsets})@footnote{File
|
|
32
|
1928 styles have only been supported since XEmacs 19.12 and Emacs 19.29.
|
|
|
1929 They work via the standard Emacs hook variable
|
|
|
1930 @code{hack-local-variables-hook}. Older Emacsen lack this hook, so file
|
|
|
1931 styles can't be used with them.}.
|
|
0
|
1932
|
|
|
1933
|
|
|
1934 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1935 @node Advanced Customizations, , Styles, Customizing Indentation
|
|
|
1936 @comment node-name, next, previous,up
|
|
|
1937
|
|
|
1938 @section Advanced Customizations
|
|
|
1939 @cindex Advanced Customizations
|
|
|
1940 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1941
|
|
|
1942 @vindex c-style-alist
|
|
|
1943 @vindex style-alist (c-)
|
|
|
1944 @vindex c-basic-offset
|
|
|
1945 @vindex basic-offset (c-)
|
|
32
|
1946 For most users, @ccmode{} will support their coding styles with
|
|
2
|
1947 very little need for more advanced customizations. Usually, one of the
|
|
|
1948 standard styles defined in @code{c-style-alist} will do the trick. At
|
|
|
1949 most, perhaps one of the syntactic symbol offsets will need to be
|
|
|
1950 tweaked slightly, or maybe @code{c-basic-offset} will need to be
|
|
|
1951 changed. However, some styles require a more flexible framework for
|
|
32
|
1952 customization, and one of the real strengths of @ccmode{} is that
|
|
2
|
1953 the syntactic analysis model provides just such a framework. This allows
|
|
32
|
1954 you to implement custom indentation calculations for situations not
|
|
2
|
1955 handled by the mode directly.
|
|
0
|
1956
|
|
32
|
1957 @vindex c-style-variables-are-local-p
|
|
|
1958 @vindex style-variables-are-local-p
|
|
|
1959 Note that the style controlling variables can either have global values,
|
|
|
1960 or can be buffer local (e.g. different in every buffer). If all the C
|
|
|
1961 files you edit tend to have the same style, you might want to keep the
|
|
|
1962 variables global. If you tend to edit files with many different styles,
|
|
|
1963 you will have to make the variables buffer local. The variable
|
|
|
1964 @code{c-style-variables-are-local-p} controls this.
|
|
|
1965
|
|
|
1966 When @code{c-style-variables-are-local-p} is non-nil, then the style
|
|
|
1967 variables will have a different settable value for each buffer,
|
|
|
1968 otherwise all buffers will share the same values. This variable only
|
|
|
1969 takes effect when @ccmode{} is loaded into your Emacs session. By
|
|
|
1970 default (for backwards compatibility reasons), its value is @code{t}.
|
|
|
1971 Note that once the variables are made buffer local, they will retain
|
|
|
1972 this property for the remainder of the current Emacs session. To change
|
|
|
1973 this behavior, set @code{c-style-variables-are-local-p} to @code{nil}
|
|
|
1974 @emph{before} you load @file{cc-mode.el}.
|
|
|
1975
|
|
0
|
1976 @menu
|
|
|
1977 * Custom Indentation Functions::
|
|
|
1978 * Custom Brace and Colon Hanging::
|
|
|
1979 * Customizing Semi-colons and Commas::
|
|
|
1980 * Other Special Indentations::
|
|
|
1981 @end menu
|
|
|
1982
|
|
|
1983 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1984 @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
|
|
|
1985 @comment node-name, next, previous,up
|
|
|
1986
|
|
|
1987 @subsection Custom Indentation Functions
|
|
|
1988 @cindex Custom Indentation Functions
|
|
|
1989 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1990
|
|
|
1991 @cindex custom indentation functions
|
|
32
|
1992 The most flexible way to customize @ccmode{} is by writing @dfn{custom
|
|
|
1993 indentation functions} and associating them with specific syntactic
|
|
|
1994 symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom
|
|
|
1995 indentation functions to provide more sophisticated indentation, for
|
|
|
1996 example when lining up C++ stream operator blocks:
|
|
0
|
1997 @example
|
|
|
1998 @group
|
|
|
1999
|
|
|
2000 1: void main(int argc, char**)
|
|
|
2001 2: @{
|
|
|
2002 3: cout << "There were "
|
|
|
2003 4: << argc
|
|
|
2004 5: << "arguments passed to the program"
|
|
|
2005 6: << endl;
|
|
|
2006 7: @}
|
|
|
2007
|
|
|
2008 @end group
|
|
|
2009 @end example
|
|
|
2010
|
|
|
2011 In this example, lines 4 through 6 are assigned the @code{stream-op}
|
|
2
|
2012 syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and
|
|
|
2013 with a @code{c-basic-offset} of 2, you can see that lines 4 through 6
|
|
|
2014 are simply indented two spaces to the right of line 3. But perhaps we'd
|
|
32
|
2015 like @ccmode{} to be a little more intelligent so that it lines up
|
|
2
|
2016 all the @samp{<<} symbols in lines 3 through 6. To do this, we have
|
|
|
2017 to write a custom indentation function which finds the column of first
|
|
|
2018 stream operator on the first line of the statement. Here is the lisp
|
|
|
2019 code (from the @file{cc-mode.el} source file) that implements this:
|
|
0
|
2020 @example
|
|
|
2021 @group
|
|
|
2022
|
|
|
2023 (defun c-lineup-streamop (langelem)
|
|
|
2024 ;; lineup stream operators
|
|
|
2025 (save-excursion
|
|
|
2026 (let* ((relpos (cdr langelem))
|
|
|
2027 (curcol (progn (goto-char relpos)
|
|
|
2028 (current-column))))
|
|
|
2029 (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
|
|
|
2030 (goto-char (match-beginning 0))
|
|
|
2031 (- (current-column) curcol))))
|
|
|
2032
|
|
|
2033 @end group
|
|
|
2034 @end example
|
|
|
2035 @noindent
|
|
|
2036 Custom indent functions take a single argument, which is a syntactic
|
|
|
2037 component cons cell (see @ref{Syntactic Analysis}). The
|
|
|
2038 function returns an integer offset value that will be added to the
|
|
2
|
2039 running total indentation for the line. Note that what actually gets
|
|
0
|
2040 returned is the difference between the column that the first stream
|
|
|
2041 operator is on, and the column of the buffer relative position passed in
|
|
32
|
2042 the function's argument. Remember that @ccmode{} automatically
|
|
0
|
2043 adds in the column of the component's relative buffer position and we
|
|
|
2044 don't want that value added into the final total twice.
|
|
|
2045
|
|
|
2046 @cindex stream-op syntactic symbol
|
|
|
2047 @findex c-lineup-streamop
|
|
|
2048 @findex lineup-streamop (c-)
|
|
|
2049 Now, to associate the function @code{c-lineup-streamop} with the
|
|
|
2050 @code{stream-op} syntactic symbol, we can add something like the
|
|
|
2051 following to our @code{c++-mode-hook}@footnote{It probably makes more
|
|
|
2052 sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
|
|
|
2053 since stream operators are only relevent for C++.}:
|
|
|
2054 @example
|
|
|
2055
|
|
|
2056 (c-set-offset 'stream-op 'c-lineup-streamop)
|
|
|
2057
|
|
|
2058 @end example
|
|
|
2059
|
|
|
2060 @kindex C-c C-q
|
|
|
2061 Now the function looks like this after re-indenting (using @kbd{C-c
|
|
|
2062 C-q}):
|
|
|
2063 @example
|
|
|
2064 @group
|
|
|
2065
|
|
|
2066 1: void main(int argc, char**)
|
|
|
2067 2: @{
|
|
|
2068 3: cout << "There were "
|
|
|
2069 4: << argc
|
|
|
2070 5: << "arguments passed to the program"
|
|
|
2071 6: << endl;
|
|
|
2072 7: @}
|
|
|
2073
|
|
|
2074 @end group
|
|
|
2075 @end example
|
|
|
2076
|
|
|
2077 @vindex c-offsets-alist
|
|
|
2078 @vindex offsets-alist (c-)
|
|
|
2079 Custom indentation functions can be as simple or as complex as you like,
|
|
|
2080 and any syntactic symbol that appears in @code{c-offsets-alist} can have
|
|
32
|
2081 a custom indentation function associated with it. @ccmode{} comes
|
|
2
|
2082 with several standard custom indentation functions, not all of which are
|
|
|
2083 used by the default styles.
|
|
|
2084
|
|
|
2085 @itemize @bullet
|
|
|
2086 @item
|
|
|
2087 @findex c-lineup-arglist
|
|
|
2088 @findex lineup-arglist (c-)
|
|
|
2089 @code{c-lineup-arglist} --- lines up function argument lines under the
|
|
|
2090 argument on the previous line.
|
|
|
2091
|
|
|
2092 @item
|
|
|
2093 @findex c-lineup-arglist-intro-after-paren
|
|
|
2094 @findex lineup-arglist-intro-after-paren (c-)
|
|
|
2095 @code{c-lineup-arglist-intro-after-paren} --- similar to
|
|
|
2096 @code{c-lineup-arglist}, but works for argument lists that begin with an
|
|
|
2097 open parenthesis followed by a newline.
|
|
|
2098
|
|
|
2099 @item
|
|
|
2100 @findex c-lineup-arglist-close-under-paren
|
|
|
2101 @findex lineup-arglist-close-under-paren (c-)
|
|
|
2102 @code{c-lineup-arglist-close-under-paren} --- set your
|
|
|
2103 @code{arglist-close} syntactic symbol to this line-up function so that
|
|
|
2104 parentheses that close argument lists will line up under the parenthesis
|
|
|
2105 that opened the argument list.
|
|
|
2106
|
|
|
2107 @item
|
|
|
2108 @findex c-lineup-streamop
|
|
|
2109 @findex lineup-streamop (c-)
|
|
|
2110 @code{c-lineup-streamop} --- lines up C++ stream operators
|
|
|
2111 (e.g. @samp{<<} and @samp{>>}).
|
|
|
2112
|
|
|
2113 @item
|
|
|
2114 @findex c-lineup-multi-inher
|
|
|
2115 @findex lineup-multi-inher (c-)
|
|
|
2116 @code{c-lineup-multi-inher} --- lines up multiple inheritance lines.
|
|
|
2117
|
|
|
2118 @item
|
|
|
2119 @findex c-lineup-C-comments
|
|
|
2120 @findex lineup-C-comments (c-)
|
|
|
2121 @code{c-lineup-C-comments} --- lines up C block comment continuation
|
|
|
2122 lines.
|
|
|
2123
|
|
|
2124 @item
|
|
|
2125 @findex c-lineup-comment
|
|
|
2126 @findex lineup-comment (c-)
|
|
|
2127 @vindex c-comment-only-line-offset
|
|
|
2128 @vindex comment-only-line-offset (c-)
|
|
|
2129 @code{c-lineup-comment} --- implements the old comment line up behavior
|
|
|
2130 specified by the variable @code{c-comment-only-line-offset}.
|
|
|
2131
|
|
|
2132 @item
|
|
|
2133 @findex c-lineup-runin-statements
|
|
|
2134 @findex lineup-runin-statements (c-)
|
|
|
2135 @code{c-lineup-runin-statements} --- lines up @code{statement}s for coding
|
|
|
2136 standards which place the first statement in a block on the same line as
|
|
|
2137 the block opening brace.
|
|
|
2138
|
|
|
2139 @item
|
|
|
2140 @findex c-lineup-math
|
|
|
2141 @findex lineup-math (c-)
|
|
|
2142 @code{c-lineup-math} --- lines up math @code{statement-cont} lines under
|
|
|
2143 the previous line after the equals sign.
|
|
|
2144
|
|
|
2145 @item
|
|
|
2146 @findex c-lineup-ObjC-method-call
|
|
|
2147 @findex lineup-ObjC-method-call (c-)
|
|
|
2148 @code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up
|
|
|
2149 selector arguments just after the message receiver.
|
|
|
2150
|
|
|
2151 @item
|
|
|
2152 @findex c-lineup-ObjC-method-args
|
|
|
2153 @findex lineup-ObjC-method-args (c-)
|
|
|
2154 @code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the
|
|
|
2155 colons that separate arguments by aligning colons vertically.
|
|
|
2156
|
|
|
2157 @item
|
|
|
2158 @findex c-lineup-ObjC-method-args-2
|
|
|
2159 @findex lineup-ObjC-method-args-2 (c-)
|
|
|
2160 @code{c-lineup-ObjC-method-args-2} --- similar to
|
|
|
2161 @code{c-lineup-ObjC-method-args} but lines up the colon on the current
|
|
|
2162 line with the colon on the previous line.
|
|
|
2163
|
|
|
2164 @end itemize
|
|
0
|
2165
|
|
|
2166 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2167 @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
|
|
|
2168 @comment node-name, next, previous,up
|
|
|
2169
|
|
|
2170 @subsection Custom Brace and Colon Hanging
|
|
|
2171 @cindex Custom Brace and Colon Hanging
|
|
|
2172 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2173
|
|
|
2174 @vindex c-hanging-braces-alist
|
|
|
2175 @vindex hanging-braces-alist (c-)
|
|
|
2176 Syntactic symbols aren't the only place where you can customize
|
|
32
|
2177 @ccmode{} with the lisp equivalent of callback functions. Brace
|
|
2
|
2178 ``hanginess'' can also be determined by custom functions associated with
|
|
0
|
2179 syntactic symbols on the @code{c-hanging-braces-alist} variable.
|
|
|
2180 Remember that @var{ACTION}'s are typically a list containing some
|
|
|
2181 combination of the symbols @code{before} and @code{after} (see
|
|
|
2182 @ref{Hanging Braces}). However, an @var{ACTION} can also be a function
|
|
|
2183 symbol which gets called when a brace matching that syntactic symbol is
|
|
|
2184 typed.
|
|
|
2185
|
|
|
2186 @cindex customizing brace hanging
|
|
|
2187 These @var{ACTION} functions are called with two arguments: the
|
|
|
2188 syntactic symbol for the brace, and the buffer position at which the
|
|
|
2189 brace was inserted. The @var{ACTION} function is expected to return a
|
|
|
2190 list containing some combination of @code{before} and @code{after}. The
|
|
|
2191 function can also return @code{nil}. This return value has the normal
|
|
2
|
2192 brace hanging semantics.
|
|
0
|
2193
|
|
32
|
2194 As an example, @ccmode{} itself uses this feature to dynamically
|
|
2
|
2195 determine the hanginess of braces which close ``do-while''
|
|
0
|
2196 constructs:
|
|
|
2197 @example
|
|
|
2198 @group
|
|
|
2199
|
|
|
2200 void do_list( int count, char** atleast_one_string )
|
|
|
2201 @{
|
|
|
2202 int i=0;
|
|
|
2203 do @{
|
|
2
|
2204 handle_string( atleast_one_string[i] );
|
|
0
|
2205 i++;
|
|
|
2206 @} while( i < count );
|
|
|
2207 @}
|
|
|
2208
|
|
|
2209 @end group
|
|
|
2210 @end example
|
|
|
2211
|
|
|
2212 @findex c-snug-do-while
|
|
|
2213 @findex snug-do-while (c-)
|
|
32
|
2214 @ccmode{} assigns the @code{block-close} syntactic symbol to the
|
|
0
|
2215 brace that closes the @code{do} construct, and normally we'd like the
|
|
|
2216 line that follows a @code{block-close} brace to begin on a separate
|
|
2
|
2217 line. However, with ``do-while'' constructs, we want the
|
|
0
|
2218 @code{while} clause to follow the closing brace. To do this, we
|
|
|
2219 associate the @code{block-close} symbol with the @var{ACTION} function
|
|
|
2220 @code{c-snug-do-while}:
|
|
|
2221 @example
|
|
|
2222
|
|
|
2223 (defun c-snug-do-while (syntax pos)
|
|
|
2224 "Dynamically calculate brace hanginess for do-while statements.
|
|
|
2225 Using this function, `while' clauses that end a `do-while' block will
|
|
|
2226 remain on the same line as the brace that closes that block.
|
|
|
2227
|
|
|
2228 See `c-hanging-braces-alist' for how to utilize this function as an
|
|
|
2229 ACTION associated with `block-close' syntax."
|
|
|
2230 (save-excursion
|
|
|
2231 (let (langelem)
|
|
|
2232 (if (and (eq syntax 'block-close)
|
|
|
2233 (setq langelem (assq 'block-close c-syntactic-context))
|
|
|
2234 (progn (goto-char (cdr langelem))
|
|
|
2235 (if (= (following-char) ?@{)
|
|
|
2236 (forward-sexp -1))
|
|
|
2237 (looking-at "\\<do\\>[^_]")))
|
|
|
2238 '(before)
|
|
|
2239 '(before after)))))
|
|
|
2240
|
|
|
2241 @end example
|
|
|
2242
|
|
2
|
2243 This function simply looks to see if the brace closes a ``do-while''
|
|
|
2244 clause and if so, returns the list @samp{(before)} indicating
|
|
0
|
2245 that a newline should be inserted before the brace, but not after it.
|
|
2
|
2246 In all other cases, it returns the list @samp{(before after)} so
|
|
0
|
2247 that the brace appears on a line by itself.
|
|
|
2248
|
|
|
2249 @vindex c-syntactic-context
|
|
|
2250 @vindex syntactic-context (c-)
|
|
|
2251 During the call to the brace hanging @var{ACTION} function, the variable
|
|
|
2252 @code{c-syntactic-context} is bound to the full syntactic analysis list.
|
|
|
2253
|
|
|
2254 @cindex customizing colon hanging
|
|
|
2255 @vindex c-hanging-colon-alist
|
|
|
2256 @vindex hanging-colon-alist (c-)
|
|
|
2257 Note that for symmetry, colon hanginess should be customizable by
|
|
|
2258 allowing function symbols as @var{ACTION}s on the
|
|
|
2259 @code{c-hanging-colon-alist} variable. Since no use has actually been
|
|
32
|
2260 found for this feature, it isn't currently implemented!
|
|
0
|
2261
|
|
|
2262 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2263 @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
|
|
|
2264 @comment node-name, next, previous,up
|
|
|
2265
|
|
|
2266 @subsection Customizing Semi-colons and Commas
|
|
|
2267 @cindex Customizing Semi-colons and Commas
|
|
|
2268 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2269
|
|
|
2270 @cindex customizing semi-colons and commas
|
|
|
2271 @vindex c-hanging-semi&comma-criteria
|
|
|
2272 @vindex hanging-semi&comma-criteria (c-)
|
|
|
2273 You can also customize the insertion of newlines after semi-colons and
|
|
|
2274 commas, when the auto-newline minor mode is enabled (see @ref{Minor
|
|
|
2275 Modes}). This is controlled by the variable
|
|
|
2276 @code{c-hanging-semi&comma-criteria}, which contains a list of functions
|
|
|
2277 that are called in the order they appear. Each function is called with
|
|
|
2278 zero arguments, and is expected to return one of the following values:
|
|
|
2279
|
|
|
2280 @itemize @bullet
|
|
|
2281 @item
|
|
2
|
2282 non-@code{nil} --- A newline is inserted, and no more functions from the
|
|
0
|
2283 list are called.
|
|
|
2284
|
|
|
2285 @item
|
|
2
|
2286 @code{stop} --- No more functions from the list are called, but no
|
|
0
|
2287 newline is inserted.
|
|
|
2288
|
|
|
2289 @item
|
|
2
|
2290 @code{nil} --- No determination is made, and the next function in the
|
|
0
|
2291 list is called.
|
|
|
2292
|
|
|
2293 @end itemize
|
|
|
2294
|
|
|
2295 If every function in the list is called without a determination being
|
|
|
2296 made, then no newline is added. The default value for this variable is a
|
|
|
2297 list containing a single function which inserts newlines only after
|
|
|
2298 semi-colons which do not appear inside parenthesis lists (i.e. those
|
|
|
2299 that separate @code{for}-clause statements).
|
|
|
2300
|
|
2
|
2301 Here's an example of a criteria function that will prevent newlines from
|
|
|
2302 being inserted after semicolons when there is a non-blank following
|
|
32
|
2303 line. Otherwise, it makes no determination. To use, add this to the
|
|
|
2304 front of the @code{c-hanging-semi&comma-criteria} list.
|
|
2
|
2305
|
|
|
2306 @example
|
|
|
2307 @group
|
|
|
2308
|
|
|
2309 (defun my-semicolon-criteria ()
|
|
|
2310 (save-excursion
|
|
|
2311 (if (and (= last-command-char ?\;)
|
|
|
2312 (zerop (forward-line 1))
|
|
|
2313 (not (looking-at "^[ \t]*$")))
|
|
|
2314 'stop
|
|
|
2315 nil)))
|
|
|
2316
|
|
|
2317 @end group
|
|
|
2318 @end example
|
|
|
2319
|
|
|
2320
|
|
0
|
2321 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2322 @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
|
|
|
2323 @comment node-name, next, previous,up
|
|
|
2324
|
|
|
2325 @subsection Other Special Indentations
|
|
|
2326 @cindex Customizing Semi-colons and Commas
|
|
|
2327 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2328
|
|
2
|
2329 @vindex c-label-minimum-indentation
|
|
|
2330 @vindex label-minimum-indentation (c-)
|
|
|
2331 In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation
|
|
32
|
2332 is imposed on lines inside top-level constructs. This minimum
|
|
|
2333 indentation is controlled by the variable
|
|
2
|
2334 @code{c-label-minimum-indentation}. The default value for this variable
|
|
|
2335 is 1.
|
|
|
2336
|
|
0
|
2337 @vindex c-special-indent-hook
|
|
|
2338 @vindex special-indent-hook (c-)
|
|
32
|
2339 One other customization variable is available in @ccmode{}:
|
|
0
|
2340 @code{c-special-indent-hook}. This is a standard hook variable that is
|
|
32
|
2341 called after every line is indented by @ccmode{}. You can use it
|
|
0
|
2342 to do any special indentation or line adjustments your style dictates,
|
|
|
2343 such as adding extra indentation to constructors or destructor
|
|
|
2344 declarations in a class definition, etc. Note however, that you should
|
|
32
|
2345 not change point or mark inside your @code{c-special-indent-hook}
|
|
0
|
2346 functions (i.e. you'll probably want to wrap your function in a
|
|
|
2347 @code{save-excursion}).
|
|
|
2348
|
|
2
|
2349 Setting @code{c-special-indent-hook} in your style definition is handled
|
|
|
2350 slightly differently than other variables. In your style definition,
|
|
|
2351 you should set the value for
|
|
|
2352 @code{c-special-indent-hook} to a function or list of functions, which
|
|
|
2353 will be appended to @code{c-special-indent-hook} using @code{add-hook}.
|
|
|
2354 That way, the current setting for the buffer local value of
|
|
|
2355 @code{c-special-indent-hook} won't be overridden.
|
|
|
2356
|
|
0
|
2357
|
|
|
2358 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2359 @node Syntactic Symbols, Performance Issues, Customizing Indentation, Top
|
|
|
2360 @comment node-name, next, previous,up
|
|
|
2361
|
|
|
2362 @chapter Syntactic Symbols
|
|
|
2363 @cindex Syntactic Symbols
|
|
|
2364 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2365
|
|
|
2366 @vindex c-offsets-alist
|
|
|
2367 @vindex offsets-alist (c-)
|
|
2
|
2368
|
|
|
2369 Here is a complete list of the recognized syntactic symbols as described
|
|
|
2370 in the @code{c-offsets-alist} variable, along with a brief description.
|
|
|
2371 More detailed descriptions follow below.
|
|
|
2372
|
|
|
2373 @itemize @bullet
|
|
|
2374 @item
|
|
|
2375 @code{string} --- inside multi-line string
|
|
|
2376 @item
|
|
|
2377 @code{c} --- inside a multi-line C style block comment
|
|
|
2378 @item
|
|
|
2379 @code{defun-open} --- brace that opens a function definition
|
|
|
2380 @item
|
|
|
2381 @code{defun-close} --- brace that closes a function definition
|
|
|
2382 @item
|
|
|
2383 @code{defun-block-intro} --- the first line in a top-level defun
|
|
|
2384 @item
|
|
|
2385 @code{class-open} --- brace that opens a class definition
|
|
|
2386 @item
|
|
|
2387 @code{class-close} --- brace that closes a class definition
|
|
|
2388 @item
|
|
|
2389 @code{inline-open} --- brace that opens an in-class inline method
|
|
|
2390 @item
|
|
|
2391 @code{inline-close} --- brace that closes an in-class inline method
|
|
|
2392 @item
|
|
32
|
2393 @code{func-decl-cont} --- the nether region between a function
|
|
|
2394 declaration's argument list and the defun opening brace. In C++ and
|
|
|
2395 Java, this can include the @code{throws} clauses of a method
|
|
|
2396 declaration.
|
|
2
|
2397 @item
|
|
|
2398 @code{knr-argdecl-intro} --- first line of a K&R C argument declaration
|
|
|
2399 @item
|
|
|
2400 @code{knr-argdecl} --- subsequent lines in a K&R C argument declaration
|
|
|
2401 @item
|
|
32
|
2402 @code{topmost-intro} --- the first line in a topmost definition
|
|
2
|
2403 @item
|
|
|
2404 @code{topmost-intro-cont} --- topmost definition continuation lines
|
|
|
2405 @item
|
|
|
2406 @code{member-init-intro} --- first line in a member initialization list
|
|
|
2407 @item
|
|
|
2408 @code{member-init-cont} --- subsequent member initialization list lines
|
|
|
2409 @item
|
|
|
2410 @code{inher-intro} --- first line of a multiple inheritance list
|
|
|
2411 @item
|
|
|
2412 @code{inher-cont} --- subsequent multiple inheritance lines
|
|
|
2413 @item
|
|
|
2414 @code{block-open} --- statement block open brace
|
|
|
2415 @item
|
|
|
2416 @code{block-close} --- statement block close brace
|
|
|
2417 @item
|
|
|
2418 @code{brace-list-open} --- open brace of an enum or static array list
|
|
|
2419 @item
|
|
|
2420 @code{brace-list-close} --- close brace of an enum or static array list
|
|
|
2421 @item
|
|
|
2422 @code{brace-list-intro} --- first line in an enum or static array list
|
|
|
2423 @item
|
|
|
2424 @code{brace-list-entry} --- subsequent lines in an enum or static array list
|
|
|
2425 @item
|
|
32
|
2426 @code{statement} --- a C statement
|
|
2
|
2427 @item
|
|
32
|
2428 @code{statement-cont} --- a continuation of a C statement
|
|
2
|
2429 @item
|
|
|
2430 @code{statement-block-intro} --- the first line in a new statement block
|
|
|
2431 @item
|
|
|
2432 @code{statement-case-intro} --- the first line in a case `block'
|
|
|
2433 @item
|
|
|
2434 @code{statement-case-open} --- the first line in a case block starting
|
|
|
2435 with brace
|
|
|
2436 @item
|
|
32
|
2437 @code{substatement} --- the first line after a conditional
|
|
2
|
2438 @item
|
|
|
2439 @code{substatement-open} --- the brace that opens a substatement block
|
|
|
2440 @item
|
|
|
2441 @code{case-label} --- a case or default label
|
|
|
2442 @item
|
|
32
|
2443 @code{access-label} --- C++ access control label
|
|
2
|
2444 @item
|
|
32
|
2445 @code{label} --- any non-special C label
|
|
2
|
2446 @item
|
|
32
|
2447 @code{do-while-closure} --- the `while' that ends a
|
|
|
2448 @code{do}-@code{while} construct
|
|
2
|
2449 @item
|
|
32
|
2450 @code{else-clause} --- the `else' of an @code{if}-@code{else} construct
|
|
2
|
2451 @item
|
|
|
2452 @code{comment-intro} --- a line containing only a comment introduction
|
|
|
2453 @item
|
|
|
2454 @code{arglist-intro} --- the first line in an argument list
|
|
|
2455 @item
|
|
|
2456 @code{arglist-cont} --- subsequent argument list lines when no arguments
|
|
|
2457 follow on the same line as the the arglist opening paren
|
|
|
2458 @item
|
|
|
2459 @code{arglist-cont-nonempty} --- subsequent argument list lines when at
|
|
|
2460 least one argument follows on the same line as the arglist opening paren
|
|
|
2461 @item
|
|
|
2462 @code{arglist-close} --- the solo close paren of an argument list
|
|
|
2463 @item
|
|
32
|
2464 @code{stream-op} --- lines continuing a stream operator
|
|
2
|
2465 @item
|
|
32
|
2466 @code{inclass} --- the line is nested inside a class definition
|
|
2
|
2467 @item
|
|
|
2468 @code{cpp-macro} --- the start of a cpp macro
|
|
|
2469 @item
|
|
|
2470 @code{friend} --- a C++ friend declaration
|
|
|
2471 @item
|
|
|
2472 @code{objc-method-intro} --- the first line of an Objective-C method definition
|
|
|
2473 @item
|
|
|
2474 @code{objc-method-args-cont} --- lines continuing an Objective-C method
|
|
|
2475 definition
|
|
|
2476 @item
|
|
|
2477 @code{objc-method-call-cont} --- lines continuing an Objective-C method call
|
|
|
2478 @item
|
|
|
2479 @code{extern-lang-open} --- brace that opens an external language block
|
|
|
2480 @item
|
|
|
2481 @code{extern-lang-close} --- brace that closes an external language block
|
|
|
2482 @item
|
|
32
|
2483 @code{inextern-lang} --- analogous to `inclass' syntactic symbol, but
|
|
|
2484 for @code{extern} blocks.
|
|
2
|
2485 @end itemize
|
|
0
|
2486
|
|
|
2487 @cindex -open syntactic symbols
|
|
|
2488 @cindex -close syntactic symbols
|
|
|
2489 Most syntactic symbol names follow a general naming convention. When a
|
|
|
2490 line begins with an open or close brace, the syntactic symbol will
|
|
|
2491 contain the suffix @code{-open} or @code{-close} respectively.
|
|
|
2492
|
|
|
2493 @cindex -intro syntactic symbols
|
|
|
2494 @cindex -cont syntactic symbols
|
|
|
2495 @cindex -block-intro syntactic symbols
|
|
|
2496 Usually, a distinction is made between the first line that introduces a
|
|
|
2497 construct and lines that continue a construct, and the syntactic symbols
|
|
|
2498 that represent these lines will contain the suffix @code{-intro} or
|
|
|
2499 @code{-cont} respectively. As a sub-classification of this scheme, a
|
|
|
2500 line which is the first of a particular brace block construct will
|
|
|
2501 contain the suffix @code{-block-intro}.
|
|
|
2502
|
|
|
2503 @kindex C-c C-s
|
|
|
2504 Let's look at some examples to understand how this works. Remember that
|
|
|
2505 you can check the syntax of any line by using @kbd{C-c C-s}.
|
|
|
2506 @example
|
|
|
2507 @group
|
|
|
2508
|
|
|
2509 1: void
|
|
|
2510 2: swap( int& a, int& b )
|
|
|
2511 3: @{
|
|
|
2512 4: int tmp = a;
|
|
|
2513 5: a = b;
|
|
|
2514 6: b = tmp;
|
|
|
2515 7: int ignored =
|
|
|
2516 8: a + b;
|
|
|
2517 9: @}
|
|
|
2518
|
|
|
2519 @end group
|
|
|
2520 @end example
|
|
|
2521
|
|
2
|
2522 @cindex topmost-intro syntactic symbol
|
|
|
2523 @cindex topmost-intro-cont syntactic symbol
|
|
|
2524 @cindex defun-open syntactic symbol
|
|
|
2525 @cindex defun-close syntactic symbol
|
|
|
2526 @cindex defun-block-intro syntactic symbol
|
|
0
|
2527 Line 1 shows a @code{topmost-intro} since it is the first line that
|
|
|
2528 introduces a top-level construct. Line 2 is a continuation of the
|
|
|
2529 top-level construct introduction so it has the syntax
|
|
|
2530 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
|
|
|
2531 the brace that opens a top-level function definition. Line 9 is a
|
|
|
2532 @code{defun-close} since it contains the brace that closes the top-level
|
|
|
2533 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
|
|
|
2534 the first line of a brace-block, which happens to be enclosed in a
|
|
|
2535 top-level function definition.
|
|
|
2536
|
|
2
|
2537 @cindex statement syntactic symbol
|
|
|
2538 @cindex statement-cont syntactic symbol
|
|
0
|
2539 Lines 5, 6, and 7 are all given @code{statement} syntax since there
|
|
|
2540 isn't much special about them. Note however that line 8 is given
|
|
|
2541 @code{statement-cont} syntax since it continues the statement begun
|
|
|
2542 on the previous line.
|
|
|
2543
|
|
|
2544 Here's another example, which illustrates some C++ class syntactic
|
|
|
2545 symbols:
|
|
|
2546 @example
|
|
|
2547 @group
|
|
|
2548
|
|
|
2549 1: class Bass
|
|
|
2550 2: : public Guitar,
|
|
|
2551 3: public Amplifiable
|
|
|
2552 4: @{
|
|
|
2553 5: public:
|
|
|
2554 6: Bass()
|
|
|
2555 7: : eString( new BassString( 0.105 )),
|
|
|
2556 8: aString( new BassString( 0.085 )),
|
|
|
2557 9: dString( new BassString( 0.065 )),
|
|
|
2558 10: gString( new BassString( 0.045 ))
|
|
|
2559 11: @{
|
|
|
2560 12: eString.tune( 'E' );
|
|
|
2561 13: aString.tune( 'A' );
|
|
|
2562 14: dString.tune( 'D' );
|
|
|
2563 15: gString.tune( 'G' );
|
|
|
2564 16: @}
|
|
2
|
2565 17: friend class Luthier;
|
|
|
2566 18: @}
|
|
0
|
2567
|
|
|
2568 @end group
|
|
|
2569 @end example
|
|
|
2570
|
|
2
|
2571 @cindex class-open syntactic symbol
|
|
|
2572 @cindex class-close syntactic symbol
|
|
0
|
2573 As in the previous example, line 1 has the @code{topmost-intro} syntax.
|
|
|
2574 Here however, the brace that opens a C++ class definition on line 4 is
|
|
2
|
2575 assigned the @code{class-open} syntax. Note that in C++, classes,
|
|
|
2576 structs, and unions are essentially equivalent syntactically (and are
|
|
|
2577 very similar semantically), so replacing the @code{class} keyword in the
|
|
|
2578 example above with @code{struct} or @code{union} would still result in a
|
|
|
2579 syntax of @code{class-open} for line 4 @footnote{This is the case even
|
|
|
2580 for C and Objective-C. For consistency, structs in all supported
|
|
|
2581 languages are syntactically equivalent to classes. Note however that
|
|
|
2582 the keyword @code{class} is meaningless in C and Objective-C.}.
|
|
|
2583 Similarly, line 18 is assigned @code{class-close} syntax.
|
|
|
2584
|
|
|
2585 @cindex inher-intro syntactic symbol
|
|
|
2586 @cindex inher-cont syntactic symbol
|
|
0
|
2587 Line 2 introduces the inheritance list for the class so it is assigned
|
|
|
2588 the @code{inher-intro} syntax, and line 3, which continues the
|
|
|
2589 inheritance list is given @code{inher-cont} syntax.
|
|
|
2590
|
|
2
|
2591 @cindex access-label syntactic symbol
|
|
|
2592 @cindex inclass syntactic symbol
|
|
|
2593 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
|
|
|
2594
|
|
|
2595 @example
|
|
|
2596 @group
|
|
|
2597
|
|
|
2598 @code{((inclass . 1) (access-label . 67))}
|
|
|
2599
|
|
|
2600 @end group
|
|
|
2601 @end example
|
|
|
2602
|
|
|
2603 @noindent
|
|
|
2604 The primary syntactic symbol for this line is @code{access-label} as
|
|
|
2605 this a label keyword that specifies access protection in C++. However,
|
|
|
2606 because this line is also a top-level construct inside a class
|
|
|
2607 definition, the analysis actually shows two syntactic symbols. The
|
|
|
2608 other syntactic symbol assigned to this line is @code{inclass}.
|
|
|
2609 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
|
|
|
2610 syntax:
|
|
|
2611
|
|
|
2612 @example
|
|
|
2613 @group
|
|
|
2614
|
|
|
2615 @code{((inclass . 58) (topmost-intro . 60))}
|
|
|
2616
|
|
|
2617 @end group
|
|
|
2618 @end example
|
|
|
2619
|
|
|
2620 @cindex member-init-intro syntactic symbol
|
|
|
2621 @cindex member-init-cont syntactic symbol
|
|
0
|
2622 Line 7 introduces a C++ member initialization list and as such is given
|
|
|
2623 @code{member-init-intro} syntax. Note that in this case it is
|
|
|
2624 @emph{not} assigned @code{inclass} since this is not considered a
|
|
|
2625 top-level construct. Lines 8 through 10 are all assigned
|
|
|
2626 @code{member-init-cont} since they continue the member initialization
|
|
|
2627 list started on line 7.
|
|
|
2628
|
|
|
2629 @cindex in-class inline methods
|
|
2
|
2630 @cindex inline-open syntactic symbol
|
|
|
2631 @cindex inline-close syntactic symbol
|
|
|
2632 But the line 11's analysis is a bit more complicated:
|
|
|
2633
|
|
|
2634 @example
|
|
|
2635 @group
|
|
|
2636
|
|
|
2637 @code{((inclass . 1) (inline-open))}
|
|
|
2638
|
|
|
2639 @end group
|
|
|
2640 @end example
|
|
|
2641
|
|
|
2642 This line is assigned a syntax of both @code{inline-open} and
|
|
|
2643 @code{inclass} because it opens an @dfn{in-class} C++ inline method
|
|
|
2644 definition. This is distinct from, but related to, the C++ notion of an
|
|
|
2645 inline function in that its definition occurs inside an enclosing class
|
|
|
2646 definition, which in C++ implies that the function should be inlined.
|
|
|
2647 For example, if the definition of the @code{Bass} constructor appeared
|
|
|
2648 outside the class definition, line 11 would be given the
|
|
|
2649 @code{defun-open} syntax, even if the keyword @code{inline} appeared
|
|
|
2650 before the method name, as in:
|
|
0
|
2651 @example
|
|
|
2652 @group
|
|
|
2653
|
|
|
2654 class Bass
|
|
|
2655 : public Guitar,
|
|
|
2656 public Amplifiable
|
|
|
2657 @{
|
|
|
2658 public:
|
|
|
2659 Bass();
|
|
|
2660 @}
|
|
|
2661
|
|
|
2662 inline
|
|
|
2663 Bass::Bass()
|
|
|
2664 : eString( new BassString( 0.105 )),
|
|
|
2665 aString( new BassString( 0.085 )),
|
|
|
2666 dString( new BassString( 0.065 )),
|
|
|
2667 gString( new BassString( 0.045 ))
|
|
|
2668 @{
|
|
|
2669 eString.tune( 'E' );
|
|
|
2670 aString.tune( 'A' );
|
|
|
2671 dString.tune( 'D' );
|
|
|
2672 gString.tune( 'G' );
|
|
|
2673 @}
|
|
|
2674
|
|
|
2675 @end group
|
|
|
2676 @end example
|
|
|
2677
|
|
2
|
2678 @cindex friend syntactic symbol
|
|
|
2679 Returning to the previous example, line 16 is given @code{inline-close}
|
|
|
2680 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
|
|
|
2681 13 through 15 are all given @code{statement} syntax. Line 17 is
|
|
|
2682 interesting in that it's syntactic analysis list contains three
|
|
|
2683 elements:
|
|
|
2684
|
|
|
2685 @example
|
|
|
2686
|
|
|
2687 @code{((friend) (inclass . 58) (topmost-intro . 380))}
|
|
|
2688
|
|
|
2689 @end example
|
|
|
2690
|
|
|
2691 The @code{friend} syntactic symbol is a modifier that typically does not
|
|
|
2692 have a relative buffer position.
|
|
0
|
2693
|
|
|
2694 Here is another (totally contrived) example which illustrates how syntax
|
|
|
2695 is assigned to various conditional constructs:
|
|
|
2696 @example
|
|
|
2697 @group
|
|
|
2698
|
|
|
2699 1: void spam( int index )
|
|
|
2700 2: @{
|
|
|
2701 3: for( int i=0; i<index; i++ )
|
|
|
2702 4: @{
|
|
|
2703 5: if( i == 10 )
|
|
|
2704 6: @{
|
|
|
2705 7: do_something_special();
|
|
|
2706 8: @}
|
|
|
2707 9: else
|
|
|
2708 10: do_something( i );
|
|
|
2709 11: @}
|
|
|
2710 12: do @{
|
|
|
2711 13: another_thing( i-- );
|
|
|
2712 14: @}
|
|
|
2713 15: while( i > 0 );
|
|
|
2714 16: @}
|
|
|
2715
|
|
|
2716
|
|
|
2717 @end group
|
|
|
2718 @end example
|
|
|
2719
|
|
|
2720 @noindent
|
|
|
2721 Only the lines that illustrate new syntactic symbols will be discussed.
|
|
|
2722
|
|
2
|
2723 @cindex substatement-open syntactic symbol
|
|
|
2724 @cindex substatement-block-intro syntactic symbol
|
|
|
2725 @cindex block-close syntactic symbol
|
|
0
|
2726 Line 4 has a brace which opens a conditional's substatement block. It
|
|
|
2727 is thus assigned @code{substatement-open} syntax, and since line 5 is
|
|
|
2728 the first line in the substatement block, it is assigned
|
|
|
2729 @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned
|
|
|
2730 similar syntax. Line 8 contains the brace that closes the inner
|
|
2
|
2731 substatement block. It is given the syntax @code{block-close},
|
|
0
|
2732 as are lines 11 and 14.
|
|
|
2733
|
|
2
|
2734 @cindex else-clause syntactic symbol
|
|
|
2735 @cindex substatement syntactic symbol
|
|
|
2736 Line 9 is a little different --- since it contains the keyword
|
|
|
2737 @code{else} matching the @code{if} statement introduced on line 5, it is
|
|
0
|
2738 given the @code{else-clause} syntax. Note also that line 10 is slightly
|
|
|
2739 different too. Because @code{else} is considered a conditional
|
|
|
2740 introducing keyword @footnote{The list of conditional keywords are (in
|
|
2
|
2741 C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do},
|
|
|
2742 @code{else}, @code{while}, and @code{switch}. C++ and Java have two
|
|
|
2743 additional conditional keywords: @code{try} and @code{catch}. Java also
|
|
|
2744 has the @code{finally} and @code{synchronized} keywords.}, and because
|
|
|
2745 the following substatement is not a brace block, line 10 is assigned the
|
|
0
|
2746 @code{substatement} syntax.
|
|
|
2747
|
|
2
|
2748 @cindex do-while-closure syntactic symbol
|
|
0
|
2749 One other difference is seen on line 15. The @code{while} construct
|
|
|
2750 that closes a @code{do} conditional is given the special syntax
|
|
|
2751 @code{do-while-closure} if it appears on a line by itself. Note that if
|
|
|
2752 the @code{while} appeared on the same line as the preceding close brace,
|
|
|
2753 that line would have been assigned @code{block-close} syntax instead.
|
|
|
2754
|
|
|
2755 Switch statements have their own set of syntactic symbols. Here's an
|
|
|
2756 example:
|
|
|
2757 @example
|
|
|
2758 @group
|
|
|
2759
|
|
|
2760 1: void spam( enum Ingredient i )
|
|
|
2761 2: @{
|
|
|
2762 3: switch( i ) @{
|
|
|
2763 4: case Ham:
|
|
|
2764 5: be_a_pig();
|
|
|
2765 6: break;
|
|
|
2766 7: case Salt:
|
|
|
2767 8: drink_some_water();
|
|
|
2768 9: break;
|
|
|
2769 10: default:
|
|
|
2770 11: @{
|
|
|
2771 12: what_is_it();
|
|
|
2772 13: break;
|
|
|
2773 14: @}
|
|
|
2774 15: @}
|
|
|
2775 14: @}
|
|
|
2776
|
|
|
2777 @end group
|
|
|
2778 @end example
|
|
|
2779
|
|
2
|
2780 @cindex case-label syntactic symbol
|
|
|
2781 @cindex statement-case-intro syntactic symbol
|
|
|
2782 @cindex statement-case-open syntactic symbol
|
|
0
|
2783 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
|
|
|
2784 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
|
|
|
2785 is treated slightly differently since it contains a brace that opens a
|
|
2
|
2786 block --- it is given @code{statement-case-open} syntax.
|
|
0
|
2787
|
|
|
2788 @cindex brace lists
|
|
|
2789 There are a set of syntactic symbols that are used to recognize
|
|
|
2790 constructs inside of brace lists. A brace list is defined as an
|
|
|
2791 @code{enum} or aggregate initializer list, such as might statically
|
|
|
2792 initialize an array of structs. For example:
|
|
|
2793 @example
|
|
|
2794 @group
|
|
|
2795
|
|
|
2796 1: static char* ingredients[] =
|
|
|
2797 2: @{
|
|
|
2798 3: "Ham",
|
|
|
2799 4: "Salt",
|
|
|
2800 5: NULL
|
|
|
2801 6: @}
|
|
|
2802
|
|
|
2803 @end group
|
|
|
2804 @end example
|
|
|
2805
|
|
2
|
2806 @cindex brace-list-open syntactic symbol
|
|
|
2807 @cindex brace-list-intro syntactic symbol
|
|
|
2808 @cindex brace-list-close syntactic symbol
|
|
|
2809 @cindex brace-list-entry syntactic symbol
|
|
0
|
2810 Following convention, line 2 in this example is assigned
|
|
|
2811 @code{brace-list-open} syntax, and line 3 is assigned
|
|
|
2812 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
|
|
|
2813 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
|
|
|
2814 @code{brace-list-entry} syntax, as would all subsequent lines in this
|
|
|
2815 initializer list.
|
|
|
2816
|
|
2
|
2817 External language definition blocks also have their own syntactic
|
|
|
2818 symbols. In this example:
|
|
|
2819 @example
|
|
|
2820 @group
|
|
|
2821
|
|
|
2822 1: extern "C"
|
|
|
2823 2: @{
|
|
|
2824 3: int thing_one( int );
|
|
|
2825 4: int thing_two( double );
|
|
|
2826 5: @}
|
|
|
2827
|
|
|
2828 @end group
|
|
|
2829 @end example
|
|
|
2830
|
|
|
2831 @cindex extern-lang-open syntactic symbol
|
|
|
2832 @cindex extern-lang-close syntactic symbol
|
|
|
2833 @cindex inextern-lang syntactic symbol
|
|
|
2834 @cindex inclass syntactic symbol
|
|
|
2835 @noindent
|
|
|
2836 line 2 is given the @code{extern-lang-open} syntax while line 5 is given
|
|
|
2837 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
|
|
|
2838 @code{((inextern-lang) (topmost-intro . 14))}, where
|
|
|
2839 @code{inextern-lang} is a modifier similar in purpose to @code{inclass}.
|
|
|
2840
|
|
0
|
2841 A number of syntactic symbols are associated with parenthesis lists,
|
|
|
2842 a.k.a argument lists, as found in function declarations and function
|
|
|
2843 calls. This example illustrates these:
|
|
|
2844 @example
|
|
|
2845 @group
|
|
|
2846
|
|
|
2847 1: void a_function( int line1,
|
|
|
2848 2: int line2 );
|
|
|
2849 3:
|
|
|
2850 4: void a_longer_function(
|
|
|
2851 5: int line1,
|
|
|
2852 6: int line2
|
|
|
2853 7: );
|
|
|
2854 8:
|
|
|
2855 9: void call_them( int line1, int line2 )
|
|
|
2856 10: @{
|
|
|
2857 11: a_function(
|
|
|
2858 12: line1,
|
|
|
2859 13: line2
|
|
|
2860 14: );
|
|
|
2861 15:
|
|
|
2862 16: a_longer_function( line1,
|
|
|
2863 17: line2 );
|
|
|
2864 18: @}
|
|
|
2865
|
|
|
2866 @end group
|
|
|
2867 @end example
|
|
|
2868
|
|
2
|
2869 @cindex arglist-intro syntactic symbol
|
|
|
2870 @cindex arglist-close syntactic symbol
|
|
0
|
2871 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
|
|
|
2872 the first line following the open parenthesis, and lines 7 and 14 are
|
|
|
2873 assigned @code{arglist-close} syntax since they contain the parenthesis
|
|
|
2874 that closes the argument list.
|
|
|
2875
|
|
2
|
2876 @cindex arglist-cont-nonempty syntactic symbol
|
|
|
2877 @cindex arglist-cont syntactic symbol
|
|
|
2878 Lines that continue argument lists can be assigned one of two syntactic
|
|
|
2879 symbols. For example, Lines 2 and 17
|
|
|
2880 are assigned @code{arglist-cont-nonempty} syntax. What this means
|
|
0
|
2881 is that they continue an argument list, but that the line containing the
|
|
2
|
2882 parenthesis that opens the list is @emph{not empty} following the open
|
|
0
|
2883 parenthesis. Contrast this against lines 6 and 13 which are assigned
|
|
|
2884 @code{arglist-cont} syntax. This is because the parenthesis that opens
|
|
32
|
2885 their argument lists is the last character on that line.
|
|
0
|
2886
|
|
|
2887 Note that there is no @code{arglist-open} syntax. This is because any
|
|
|
2888 parenthesis that opens an argument list, appearing on a separate line,
|
|
|
2889 is assigned the @code{statement-cont} syntax instead.
|
|
|
2890
|
|
|
2891 A few miscellaneous syntactic symbols that haven't been previously
|
|
32
|
2892 covered are illustrated by this C++ example:
|
|
0
|
2893 @example
|
|
|
2894 @group
|
|
|
2895
|
|
|
2896 1: void Bass::play( int volume )
|
|
|
2897 2: const
|
|
|
2898 3: @{
|
|
|
2899 4: /* this line starts a multi-line
|
|
|
2900 5: * comment. This line should get `c' syntax */
|
|
|
2901 6:
|
|
32
|
2902 7: char* a_multiline_string = "This line starts a multi-line \
|
|
0
|
2903 8: string. This line should get `string' syntax.";
|
|
|
2904 9:
|
|
|
2905 10: note:
|
|
|
2906 11: @{
|
|
|
2907 12: #ifdef LOCK
|
|
|
2908 13: Lock acquire();
|
|
|
2909 14: #endif // LOCK
|
|
|
2910 15: slap_pop();
|
|
|
2911 16: cout << "I played "
|
|
|
2912 17: << "a note\n";
|
|
|
2913 18: @}
|
|
|
2914 19: @}
|
|
|
2915
|
|
|
2916 @end group
|
|
|
2917 @end example
|
|
|
2918
|
|
|
2919 @cindex modifier syntactic symbol
|
|
|
2920 The lines to note in this example include:
|
|
|
2921
|
|
|
2922 @itemize @bullet
|
|
|
2923
|
|
32
|
2924 @cindex func-decl-cont syntactic symbol
|
|
0
|
2925 @item
|
|
32
|
2926 line 2, assigned the @code{func-decl-cont} syntax;
|
|
2
|
2927
|
|
|
2928 @cindex comment-intro syntactic symbol
|
|
0
|
2929 @item
|
|
2
|
2930 line 4, assigned both @code{defun-block-intro} @emph{and}
|
|
32
|
2931 @code{comment-intro} syntax;
|
|
2
|
2932
|
|
|
2933 @cindex c syntactic symbol
|
|
0
|
2934 @item
|
|
2
|
2935 line 5, assigned @code{c} syntax;
|
|
0
|
2936
|
|
|
2937 @item
|
|
|
2938 @cindex syntactic whitespace
|
|
|
2939 line 6 which, even though it contains nothing but whitespace, is
|
|
|
2940 assigned @code{defun-block-intro}. Note that the appearance of the
|
|
|
2941 comment on lines 4 and 5 do not cause line 6 to be assigned
|
|
|
2942 @code{statement} syntax because comments are considered to be
|
|
2
|
2943 @dfn{syntactic whitespace}, which are ignored when analyzing
|
|
0
|
2944 code;
|
|
|
2945
|
|
2
|
2946 @cindex string syntactic symbol
|
|
0
|
2947 @item
|
|
2
|
2948 line 8, assigned @code{string} syntax;
|
|
|
2949
|
|
|
2950 @cindex label syntactic symbol
|
|
0
|
2951 @item
|
|
2
|
2952 line 10, assigned @code{label} syntax;
|
|
|
2953
|
|
|
2954 @cindex block-open syntactic symbol
|
|
0
|
2955 @item
|
|
2
|
2956 line 11, assigned @code{block-open} syntax;
|
|
|
2957
|
|
|
2958 @cindex cpp-macro syntactic symbol
|
|
0
|
2959 @item
|
|
2
|
2960 lines 12 and 14, assigned @code{cpp-macro} syntax;
|
|
|
2961
|
|
|
2962 @cindex stream-op syntactic symbol
|
|
0
|
2963 @item
|
|
32
|
2964 line 17, assigned @code{stream-op} syntax.
|
|
0
|
2965
|
|
|
2966 @end itemize
|
|
|
2967
|
|
|
2968 In Objective-C buffers, there are three additional syntactic symbols
|
|
|
2969 assigned to various message calling constructs. Here's an example
|
|
|
2970 illustrating these:
|
|
|
2971 @example
|
|
|
2972 @group
|
|
|
2973
|
|
|
2974 1: - (void)setDelegate:anObject
|
|
|
2975 2: withStuff:stuff
|
|
|
2976 3: @{
|
|
|
2977 4: [delegate masterWillRebind:self
|
|
|
2978 5: toDelegate:anObject
|
|
|
2979 6: withExtraStuff:stuff];
|
|
|
2980 7: @}
|
|
|
2981
|
|
|
2982 @end group
|
|
|
2983 @end example
|
|
|
2984
|
|
2
|
2985 @cindex objc-method-intro syntactic symbol
|
|
|
2986 @cindex objc-method-args-cont syntactic symbol
|
|
|
2987 @cindex objc-method-call-cont syntactic symbol
|
|
0
|
2988 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
|
|
|
2989 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
|
|
|
2990 assigned @code{objc-method-call-cont} syntax.
|
|
|
2991
|
|
2
|
2992 @cindex knr-argdecl-intro
|
|
|
2993 @cindex knr-argdecl
|
|
|
2994 Two other syntactic symbols can appear in old style, non-prototyped C
|
|
|
2995 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
|
|
|
2996 @example
|
|
|
2997 @group
|
|
|
2998
|
|
|
2999 1: int add_three_integers(a, b, c)
|
|
|
3000 2: int a;
|
|
|
3001 3: int b;
|
|
|
3002 4: int c;
|
|
|
3003 5: @{
|
|
|
3004 6: return a + b + c;
|
|
|
3005 7: @}
|
|
|
3006
|
|
|
3007 @end group
|
|
|
3008 @end example
|
|
|
3009
|
|
|
3010 Here, line 2 is the first line in an argument declaration list and so is
|
|
|
3011 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
|
|
|
3012 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
|
|
|
3013 syntax.
|
|
0
|
3014
|
|
|
3015 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3016 @node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top
|
|
|
3017 @comment node-name, next, previous,up
|
|
|
3018
|
|
|
3019 @chapter Performance Issues
|
|
|
3020 @cindex Performance Issues
|
|
|
3021 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3022
|
|
|
3023 C and it's derivative languages are highly complex creatures. Often,
|
|
32
|
3024 ambiguous code situations arise that require @ccmode{} to scan
|
|
2
|
3025 large portions of the buffer to determine syntactic context. Such
|
|
|
3026 pathological code@footnote{such as the output of @code{lex(1)}!}
|
|
32
|
3027 can cause @ccmode{} to perform fairly badly.
|
|
0
|
3028 This section identifies some of the coding styles to watch out for, and
|
|
|
3029 suggests some workarounds that you can use to improve performance.
|
|
|
3030
|
|
32
|
3031 Because @ccmode{} has to scan the buffer backwards from the current
|
|
0
|
3032 insertion point, and because C's syntax is fairly difficult to parse in
|
|
32
|
3033 the backwards direction, @ccmode{} often tries to find the nearest
|
|
0
|
3034 position higher up in the buffer from which to begin a forward scan.
|
|
|
3035 The farther this position is from the current insertion point, the
|
|
32
|
3036 slower the mode gets. Some coding styles can even force @ccmode{}
|
|
0
|
3037 to scan from the beginning of the buffer!
|
|
|
3038
|
|
|
3039 @findex beginning-of-defun
|
|
|
3040 @findex defun-prompt-regexp
|
|
|
3041 One of the simplest things you can do to reduce scan time, is make sure
|
|
|
3042 any brace that opens a top-level block construct always appears in the
|
|
|
3043 leftmost column. This is actually an Emacs constraint, as embodied in
|
|
32
|
3044 the @code{beginning-of-defun} function which @ccmode{} uses
|
|
0
|
3045 heavily. If you insist on hanging top-level open braces on the right
|
|
|
3046 side of the line, then you should set the variable
|
|
|
3047 @code{defun-prompt-regexp} to something reasonable @footnote{Note that
|
|
|
3048 this variable is only defined in Emacs 19.}, however that ``something
|
|
32
|
3049 reasonable'' is difficult to define, so @ccmode{} doesn't do it
|
|
0
|
3050 for you.
|
|
|
3051
|
|
32
|
3052 @vindex c-Java-defun-prompt-regexp
|
|
|
3053 @vindex Java-defun-prompt-regexp (c-)
|
|
|
3054 A special note about @code{defun-prompt-regexp} in Java mode: while much
|
|
|
3055 of the early sample Java code seems to encourage a style where the brace
|
|
|
3056 that opens a class is hung on the right side of the line, this is not a
|
|
|
3057 good style to pursue in Emacs. @ccmode{} comes with a variable
|
|
|
3058 @code{c-Java-defun-prompt-regexp} which tries to define a regular
|
|
|
3059 expression usable for this style, but there are problems with it. In
|
|
|
3060 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
|
|
|
3061 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
|
|
|
3062 it is not used by default, but if you feel adventurous, you can set
|
|
|
3063 @code{defun-prompt-regexp} to it in your mode hook. In any event,
|
|
|
3064 setting and rely on @code{defun-prompt-regexp} will definitely slow
|
|
|
3065 things down!
|
|
|
3066
|
|
|
3067 You will probably notice pathological behavior from @ccmode{} when
|
|
0
|
3068 working in files containing large amounts of cpp macros. This is
|
|
32
|
3069 because @ccmode{} cannot quickly skip backwards over these lines.
|
|
0
|
3070
|
|
|
3071 @vindex c-recognize-knr-p
|
|
|
3072 @vindex recognize-knr-p (c-)
|
|
32
|
3073 Previous versions of @ccmode{} had potential performance problems
|
|
|
3074 when recognizing K&R style function argument declarations. This was
|
|
2
|
3075 because there are ambiguities in the C syntax when K&R style argument
|
|
32
|
3076 lists are used@footnote{It is hard to distinguish them from top-level
|
|
|
3077 declarations.}. @ccmode{} has adopted BOCM's convention for
|
|
2
|
3078 limiting the search: it assumes that argdecls are indented at least one
|
|
|
3079 space, and that the function headers are not indented at all. With
|
|
32
|
3080 current versions of @ccmode{}, user customization of
|
|
|
3081 @code{c-recognize-knr-p} is deprecated. Just don't put argdecls in
|
|
|
3082 column zero!
|
|
2
|
3083
|
|
|
3084 @cindex @file{cc-lobotomy.el} file
|
|
0
|
3085 @vindex cc-lobotomy-pith-list
|
|
32
|
3086 You might want to investigate the speed-ups contained in the
|
|
|
3087 file @file{cc-lobotomy.el}, which is part of the @ccmode{} distribution.
|
|
|
3088 As mentioned previous, @ccmode{} always trades accuracy for speed,
|
|
|
3089 however it is recognized that sometimes you need speed and can sacrifice
|
|
|
3090 some accuracy in indentation. The file @file{cc-lobotomy.el} contains
|
|
|
3091 hacks that will ``dumb down'' @ccmode{} in some specific ways, making
|
|
|
3092 that trade-off of speed for accuracy. I won't go into details of its
|
|
|
3093 use here; you should read the comments at the top of the file, and look
|
|
|
3094 at the variable @code{cc-lobotomy-pith-list} for details.
|
|
0
|
3095
|
|
|
3096
|
|
|
3097 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
32
|
3098 @node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top
|
|
0
|
3099 @comment node-name, next, previous,up
|
|
|
3100
|
|
|
3101 @chapter Frequently Asked Questions
|
|
|
3102 @cindex Frequently Asked Questions
|
|
2
|
3103 @comment FAQ
|
|
0
|
3104 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3105
|
|
|
3106 @kindex C-x h
|
|
|
3107 @kindex ESC C-\
|
|
|
3108 @kindex ESC C-x
|
|
|
3109 @kindex C-c C-q
|
|
|
3110 @kindex ESC C-q
|
|
|
3111 @kindex ESC C-u
|
|
|
3112 @kindex RET
|
|
|
3113 @kindex LFD
|
|
|
3114 @findex newline-and-indent
|
|
|
3115 @quotation
|
|
|
3116
|
|
|
3117 @strong{Q.} @emph{How do I re-indent the whole file?}
|
|
|
3118
|
|
|
3119 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
|
|
|
3120 buffer. Then hit @kbd{@key{ESC} C-\}.
|
|
2
|
3121 @sp 1
|
|
0
|
3122
|
|
|
3123 @strong{Q.} @emph{How do I re-indent the entire function?
|
|
|
3124 @kbd{@key{ESC} C-x} doesn't work.}
|
|
|
3125
|
|
|
3126 @strong{A.} @kbd{@key{ESC} C-x} is reserved for future Emacs use.
|
|
|
3127 To re-indent the entire function hit @kbd{C-c C-q}.
|
|
2
|
3128 @sp 1
|
|
0
|
3129
|
|
|
3130 @strong{Q.} @emph{How do I re-indent the current block?}
|
|
|
3131
|
|
|
3132 @strong{A.} First move to the brace which opens the block with
|
|
|
3133 @kbd{@key{ESC} C-u}, then re-indent that expression with
|
|
|
3134 @kbd{@key{ESC} C-q}.
|
|
2
|
3135 @sp 1
|
|
0
|
3136
|
|
|
3137 @strong{Q.} @emph{Why doesn't the @key{RET} key indent the line to
|
|
|
3138 where the new text should go after inserting the newline?}
|
|
|
3139
|
|
|
3140 @strong{A.} Emacs' convention is that @key{RET} just adds a newline,
|
|
|
3141 and that @key{LFD} adds a newline and indents it. You can make
|
|
|
3142 @key{RET} do this too by adding this to your
|
|
|
3143 @code{c-mode-common-hook} (see the sample @file{.emacs} file
|
|
|
3144 @ref{Sample .emacs File}):
|
|
|
3145 @example
|
|
|
3146
|
|
|
3147 (define-key c-mode-map "\C-m" 'newline-and-indent)
|
|
|
3148
|
|
|
3149 @end example
|
|
|
3150
|
|
32
|
3151 This is a very common question. If you want this to be the default
|
|
|
3152 behavior, don't lobby me, lobby RMS! @code{:-)}
|
|
2
|
3153 @sp 1
|
|
0
|
3154
|
|
|
3155 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
|
|
|
3156 in my @file{.emacs} file but I get an error saying that
|
|
|
3157 @code{c-set-offset}'s function definition is void.}
|
|
|
3158
|
|
32
|
3159 @strong{A.} This means that @ccmode{} wasn't loaded into your
|
|
0
|
3160 Emacs session by the time the @code{c-set-offset} call was reached,
|
|
32
|
3161 mostly likely because @ccmode{} is being autoloaded. Instead
|
|
0
|
3162 of putting the @code{c-set-offset} line in your top-level
|
|
|
3163 @file{.emacs} file, put it in your @code{c-mode-common-hook}, or
|
|
|
3164 simply add the following to the top of your @file{.emacs} file:
|
|
|
3165 @example
|
|
|
3166
|
|
|
3167 (require 'cc-mode)
|
|
|
3168
|
|
|
3169 @end example
|
|
|
3170
|
|
|
3171 See the sample @file{.emacs} file @ref{Sample .emacs File} for
|
|
|
3172 details.
|
|
|
3173
|
|
2
|
3174 @sp 1
|
|
0
|
3175 @strong{Q.} @emph{How do I make strings, comments, keywords, and other
|
|
|
3176 constructs appear in different colors, or in bold face, etc.?}
|
|
|
3177
|
|
|
3178 @strong{A.} ``Syntax Colorization'' is an Emacs 19 feature, controlled
|
|
32
|
3179 by @code{font-lock-mode}. It is not part of @ccmode{}.
|
|
0
|
3180
|
|
2
|
3181 @sp 1
|
|
|
3182 @strong{Q.} @emph{I @code{setq} @code{c-basic-offset} to 4 in my
|
|
|
3183 @file{.emacs} file, but why does everything still get indented with only
|
|
|
3184 2 spaces?}
|
|
|
3185
|
|
32
|
3186 @vindex c-style-variables-are-local-p
|
|
|
3187 @vindex style-variables-are-local-p
|
|
|
3188 @strong{A.} It's because @code{c-basic-offset} is, by default, a
|
|
|
3189 ``buffer local variable'', meaning its value is unique to each buffer.
|
|
|
3190 The prefered way to customize this is to change its value in a ``mode
|
|
|
3191 hook'' (most likely @code{c-mode-common-hook}). Alternatively you can
|
|
|
3192 use @code{setq-default} to change its value globally. Better yet,
|
|
|
3193 before you load @file{cc-mode.el}, set the variable
|
|
|
3194 @code{c-style-variables-are-local-p} to @code{nil}. @xref{Advanced
|
|
|
3195 Customizations}.
|
|
2
|
3196
|
|
0
|
3197 @end quotation
|
|
|
3198
|
|
|
3199
|
|
|
3200 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
32
|
3201 @node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top
|
|
0
|
3202 @comment node-name, next, previous,up
|
|
|
3203
|
|
32
|
3204 @chapter Getting the latest CC Mode release
|
|
|
3205 @cindex Getting the latest CC Mode release
|
|
0
|
3206 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3207
|
|
32
|
3208 @ccmode{} is now distributed with Emacs 19, XEmacs 19, and XEmacs 20, so
|
|
0
|
3209 you would typically just use the version that comes with your Emacs.
|
|
2
|
3210 These may be slightly out of date due to release schedule skew, so you
|
|
|
3211 should always check the canonical site for the latest version.
|
|
0
|
3212
|
|
|
3213 @example
|
|
2
|
3214 @group
|
|
|
3215
|
|
|
3216 World Wide Web:
|
|
|
3217
|
|
|
3218 @code{http://www.python.org/ftp/emacs/}
|
|
|
3219
|
|
|
3220 Anonymous FTP:
|
|
|
3221
|
|
|
3222 @code{ftp://ftp.python.org/pub/emacs/}
|
|
|
3223
|
|
|
3224 @end group
|
|
0
|
3225 @end example
|
|
|
3226
|
|
2
|
3227 There are many files under these directories; you can pick up the entire
|
|
|
3228 distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of
|
|
|
3229 the individual files, including PostScript documentation.
|
|
0
|
3230
|
|
32
|
3231 If you do not have World Wide Web, or anonymous ftp access, you can get
|
|
|
3232 the distribution through an anonymous ftp-to-mail gateway, such as the
|
|
|
3233 one run by DEC at:
|
|
|
3234 @example
|
|
|
3235
|
|
|
3236 @code{ftpmail@@decwrl.dec.com}
|
|
|
3237
|
|
|
3238 @end example
|
|
|
3239 To get @ccmode{} via email, send the following message in the body of
|
|
|
3240 your mail to that address:
|
|
0
|
3241 @example
|
|
|
3242
|
|
|
3243 reply <a valid net address back to you>
|
|
|
3244 connect ftp.python.org
|
|
|
3245 binary
|
|
|
3246 uuencode
|
|
|
3247 chdir pub/emacs
|
|
|
3248 get cc-mode.tar.gz
|
|
|
3249
|
|
|
3250 @end example
|
|
|
3251 @noindent
|
|
|
3252 or just send the message "help" for more information on ftpmail.
|
|
2
|
3253 Response times will vary with the number of requests in the queue. I am
|
|
|
3254 in no way connected to this service, so I make no claims or guarantees
|
|
|
3255 about its availability!
|
|
0
|
3256
|
|
|
3257 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
32
|
3258 @node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top
|
|
0
|
3259 @comment node-name, next, previous,up
|
|
|
3260
|
|
32
|
3261 @chapter Sample .emacs file
|
|
|
3262 @cindex Sample .emacs file
|
|
0
|
3263 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3264
|
|
|
3265 @example
|
|
|
3266 ;; Here's a sample .emacs file that might help you along the way. Just
|
|
|
3267 ;; copy this region and paste it into your .emacs file. You may want to
|
|
|
3268 ;; change some of the actual values.
|
|
|
3269
|
|
|
3270 (defconst my-c-style
|
|
32
|
3271 '((c-tab-always-indent . t)
|
|
|
3272 (c-comment-only-line-offset . 4)
|
|
|
3273 (c-hanging-braces-alist . ((substatement-open after)
|
|
|
3274 (brace-list-open)))
|
|
|
3275 (c-hanging-colons-alist . ((member-init-intro before)
|
|
|
3276 (inher-intro)
|
|
|
3277 (case-label after)
|
|
|
3278 (label after)
|
|
|
3279 (access-label after)))
|
|
|
3280 (c-cleanup-list . (scope-operator
|
|
|
3281 empty-defun-braces
|
|
|
3282 defun-close-semi))
|
|
|
3283 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
|
|
|
3284 (substatement-open . 0)
|
|
|
3285 (case-label . 4)
|
|
|
3286 (block-open . 0)
|
|
|
3287 (knr-argdecl-intro . -)))
|
|
0
|
3288 (c-echo-syntactic-information-p . t)
|
|
|
3289 )
|
|
|
3290 "My C Programming Style")
|
|
|
3291
|
|
|
3292 ;; Customizations for all of c-mode, c++-mode, and objc-mode
|
|
|
3293 (defun my-c-mode-common-hook ()
|
|
|
3294 ;; add my personal style and set it for the current buffer
|
|
|
3295 (c-add-style "PERSONAL" my-c-style t)
|
|
|
3296 ;; offset customizations not in my-c-style
|
|
|
3297 (c-set-offset 'member-init-intro '++)
|
|
|
3298 ;; other customizations
|
|
|
3299 (setq tab-width 8
|
|
|
3300 ;; this will make sure spaces are used instead of tabs
|
|
|
3301 indent-tabs-mode nil)
|
|
|
3302 ;; we like auto-newline and hungry-delete
|
|
|
3303 (c-toggle-auto-hungry-state 1)
|
|
2
|
3304 ;; keybindings for all supported languages. We can put these in
|
|
|
3305 ;; c-mode-map because c++-mode-map, objc-mode-map, and java-mode-map
|
|
|
3306 ;; inherit from it.
|
|
0
|
3307 (define-key c-mode-map "\C-m" 'newline-and-indent)
|
|
|
3308 )
|
|
|
3309
|
|
|
3310 ;; the following only works in Emacs 19
|
|
|
3311 ;; Emacs 18ers can use (setq c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
3312 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
3313 @end example
|
|
|
3314
|
|
|
3315 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
2
|
3316 @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top
|
|
0
|
3317 @comment node-name, next, previous,up
|
|
|
3318 @chapter Limitations and Known Bugs
|
|
|
3319 @cindex Limitations and Known Bugs
|
|
|
3320 @comment * Limitations and Known Bugs
|
|
|
3321 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3322
|
|
|
3323 @itemize @bullet
|
|
|
3324 @item
|
|
|
3325 Multi-line macros are not handled properly.
|
|
|
3326
|
|
|
3327 @item
|
|
|
3328 Re-indenting large regions or expressions can be slow.
|
|
|
3329
|
|
|
3330 @item
|
|
32
|
3331 Use with Emacs 18 can be slow and annoying. You should seriously
|
|
0
|
3332 consider upgrading to Emacs 19.
|
|
|
3333
|
|
|
3334 @item
|
|
32
|
3335 Add-on fill packages may not work as well as @ccmode{}'s built-in
|
|
|
3336 filling routines. I no longer recommend you use @code{filladapt} to
|
|
|
3337 fill comments.
|
|
2
|
3338
|
|
|
3339 @cindex c-indent-exp
|
|
|
3340 @cindex indent-exp (c-)
|
|
0
|
3341 @item
|
|
2
|
3342 @code{c-indent-exp} has not been fully optimized. It essentially
|
|
|
3343 equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every
|
|
|
3344 line. Some information is cached from line to line, but such caching
|
|
|
3345 invariable causes inaccuracies in analysis in some bizarre situations.
|
|
0
|
3346
|
|
|
3347 @end itemize
|
|
|
3348
|
|
|
3349 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3350 @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top
|
|
|
3351 @comment node-name, next, previous,up
|
|
|
3352 @chapter Mailing Lists and Submitting Bug Reports
|
|
|
3353 @cindex Mailing Lists and Submitting Bug Reports
|
|
|
3354 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3355
|
|
|
3356 @kindex C-c C-b
|
|
|
3357 @findex c-submit-bug-report
|
|
|
3358 @findex submit-bug-report (c-)
|
|
|
3359 @cindex beta testers mailing list
|
|
|
3360 @cindex announcement mailing list
|
|
|
3361 To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report})
|
|
|
3362 command. This provides vital information I need to reproduce your
|
|
|
3363 problem. Make sure you include a concise, but complete code example.
|
|
|
3364 Please try to boil your example down to just the essential code needed
|
|
|
3365 to reproduce the problem, and include an exact recipe of steps needed to
|
|
|
3366 expose the bug. Be especially sure to include any code that appears
|
|
2
|
3367 @emph{before} your bug example, if you think it might affect my ability
|
|
|
3368 to reproduce it.
|
|
|
3369
|
|
|
3370 Bug reports are now sent to the following email addresses:
|
|
|
3371 @code{cc-mode-help@@python.org} and
|
|
32
|
3372 @code{bug-gnu-emacs@@prep.ai.mit.edu}; the latter is mirrored on the
|
|
|
3373 Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions,
|
|
|
3374 suggestions, and kudos to @code{cc-mode-help@@python.org}, or
|
|
|
3375 @code{help-gnu-emacs@@prep.ai.mit.edu} which is mirrored on newsgroup
|
|
0
|
3376 @code{gnu.emacs.help}.
|
|
|
3377
|
|
|
3378
|
|
|
3379 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3380 @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top
|
|
|
3381 @comment node-name, next, previous, up
|
|
|
3382 @unnumbered Concept Index
|
|
|
3383 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3384
|
|
|
3385 @printindex cp
|
|
|
3386
|
|
|
3387
|
|
|
3388 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3389 @node Command Index, Key Index, Concept Index, Top
|
|
|
3390 @comment node-name, next, previous, up
|
|
|
3391 @unnumbered Command Index
|
|
|
3392 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3393
|
|
|
3394 @ifinfo
|
|
|
3395
|
|
|
3396 @end ifinfo
|
|
32
|
3397 Since all @ccmode{} commands are prepended with the string
|
|
2
|
3398 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
|
|
|
3399 @code{@var{<thing>} (c-)} name.
|
|
0
|
3400 @iftex
|
|
|
3401 @sp 2
|
|
|
3402 @end iftex
|
|
|
3403 @printindex fn
|
|
|
3404
|
|
|
3405
|
|
|
3406 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3407 @node Key Index, Variable Index, Command Index, Top
|
|
|
3408 @comment node-name, next, previous, up
|
|
|
3409 @unnumbered Key Index
|
|
|
3410 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3411
|
|
|
3412 @printindex ky
|
|
|
3413
|
|
|
3414
|
|
|
3415 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3416 @node Variable Index, , Key Index, Top
|
|
|
3417 @comment node-name, next, previous, up
|
|
|
3418 @unnumbered Variable Index
|
|
|
3419 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
3420
|
|
32
|
3421 Since all @ccmode{} variables are prepended with the string
|
|
2
|
3422 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
|
|
|
3423 @code{@var{<thing>} (c-)} name.
|
|
0
|
3424 @iftex
|
|
|
3425 @sp 2
|
|
|
3426 @end iftex
|
|
|
3427 @printindex vr
|
|
|
3428 @summarycontents
|
|
|
3429 @contents
|
|
|
3430 @bye
|
