|
0
|
1 \input texinfo @c -*- texinfo -*-
|
|
|
2
|
|
|
3 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
4 @comment %**start of header (This is for running Texinfo on a region)
|
|
|
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
6
|
|
|
7 @setfilename ../info/cc-mode.info
|
|
|
8 @settitle CC-MODE Version 4 Documentation
|
|
|
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
|
|
|
20 @comment manual version: 2.35
|
|
|
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>
|
|
|
25 @comment Last modification: 1996/01/19 20:50:48
|
|
|
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
|
|
|
36 Copyright @copyright{} 1995 Free Software Foundation, Inc.
|
|
|
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
|
|
|
51 @center @titlefont{CC-MODE Version 4}
|
|
|
52 @sp 2
|
|
|
53 @center A GNU Emacs mode for editing C, C++, and Objective-C code.
|
|
|
54 @center (manual revision: 2.35)
|
|
|
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::
|
|
|
87 * Indentation Commands::
|
|
|
88 * Customizing Indentation::
|
|
|
89 * Syntactic Symbols::
|
|
|
90 * Performance Issues::
|
|
|
91 * Frequently Asked Questions::
|
|
|
92 * Getting the latest cc-mode release::
|
|
|
93 * Sample .emacs File::
|
|
|
94 * Requirements::
|
|
|
95 * Limitations and Known Bugs::
|
|
|
96 * Mailing Lists and Submitting Bug Reports::
|
|
|
97 * Concept Index::
|
|
|
98 * Command Index:: Command Index
|
|
|
99 * Key Index:: Key Index
|
|
|
100 * Variable Index:: Variable Index
|
|
|
101 @end menu
|
|
|
102
|
|
|
103 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
104 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
105
|
|
|
106 @node Introduction, Getting Connected, Top, Top
|
|
|
107 @comment node-name, next, previous, up
|
|
|
108 @chapter Introduction
|
|
|
109 @cindex Introduction
|
|
|
110
|
|
|
111 @cindex BOCM
|
|
|
112 Welcome to @code{cc-mode}, version 4. This is a GNU Emacs mode for
|
|
|
113 editing files containing C, C++, Objective-C, and Java code.
|
|
|
114 This incarnation of the mode is descendant from @file{c-mode.el} (also
|
|
|
115 called "Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el}
|
|
|
116 version 2, which I have been maintaining since 1992. @code{cc-mode}
|
|
|
117 represents a significant milestone in the mode's life. It has been
|
|
|
118 fully merged back with Emacs 19's @file{c-mode.el}. Also a new, more
|
|
|
119 intuitive and flexible mechanism for controlling indentation has been
|
|
|
120 developed.
|
|
|
121
|
|
|
122 @code{cc-mode} version 4 supports the editing of K&R and ANSI C,
|
|
|
123 @dfn{ARM} @footnote{i.e. ``The Annotated C++ Reference Manual'', by
|
|
|
124 Ellis and Stroustrup.} C++, Objective-C, and Java files. In this way,
|
|
|
125 you can easily set up consistent coding styles for use in editing all C,
|
|
|
126 C++, Objective-C, and Java programs.
|
|
|
127
|
|
|
128 This manual will describe the following:
|
|
|
129
|
|
|
130 @itemize @bullet
|
|
|
131 @item
|
|
|
132 How to get started using @code{cc-mode}.
|
|
|
133
|
|
|
134 @item
|
|
|
135 How the new indentation engine works.
|
|
|
136
|
|
|
137 @item
|
|
|
138 How to customize the new indentation engine.
|
|
|
139
|
|
|
140 @end itemize
|
|
|
141
|
|
|
142 Note that the name of this file is @file{cc-mode.el}, and I'll often
|
|
|
143 refer to the package as @code{cc-mode}, but there really is no top level
|
|
|
144 @code{cc-mode} entry point. I call it @code{cc-mode} simply to
|
|
|
145 differentiate it from @file{c-mode.el}. All of the variables, commands,
|
|
|
146 and functions in @code{cc-mode} are prefixed with @code{c-<thing>}, and
|
|
|
147 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, and @code{java-mode}
|
|
|
148 entry points are provided. This file is intended to be a replacement
|
|
|
149 for @file{c-mode.el} and @file{c++-mode.el}.
|
|
|
150
|
|
|
151 @findex c-version
|
|
|
152 The major version number was incremented to 4 with the addition of
|
|
|
153 @code{objc-mode}. To find the minor revision number of this release, use
|
|
|
154 @kbd{M-x c-version RET}. Work has already begun on @code{cc-mode}
|
|
|
155 version 5, in which Emacs 18 will not be supported.
|
|
|
156
|
|
|
157 As of this writing (19-Jan-1996), both Emacs 19.30 and XEmacs 19.13 are
|
|
|
158 distributed with @code{cc-mode}. Emacs 19.31 and XEmacs 19.14 will both
|
|
|
159 contain the latest version of cc-mode when it is released. If you are
|
|
|
160 running older versions of these Emacsen, you may want to upgrade your
|
|
|
161 copy of @code{cc-mode}. See @ref{Getting the latest cc-mode release}.
|
|
|
162
|
|
|
163 @cindex @file{cc-compat.el} file
|
|
|
164 This distribution also contains a file called @file{cc-compat.el}
|
|
|
165 which should ease your transition from BOCM to @code{cc-mode}. It
|
|
|
166 currently comes unguaranteed and unsupported, but this may change for
|
|
|
167 future versions.
|
|
|
168
|
|
|
169 A special word of thanks goes to Krishna Padmasola for his work in
|
|
|
170 converting the original @file{README} file to texinfo format.
|
|
|
171 @code{cc-mode} users have been clamoring for a manual for a long time,
|
|
|
172 and thanks to Krishna, it is now available <clap> <clap> <clap>!
|
|
|
173 @code{:-)}
|
|
|
174
|
|
|
175
|
|
|
176 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
177
|
|
|
178 @node Getting Connected, New Indentation Engine, Introduction, Top
|
|
|
179 @comment node-name, next, previous, up
|
|
|
180 @chapter Getting Connected
|
|
|
181 @cindex Getting Connected
|
|
|
182
|
|
|
183 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
184
|
|
|
185 @file{cc-mode.el} works well with the 2 main branches of Emacs 19:
|
|
|
186 XEmacs and the Emacs 19 maintained by the FSF. Emacs 19 users will want
|
|
|
187 to use Emacs version 19.21 or better, XEmacs users will want 19.6 or
|
|
|
188 better. Earlier versions of these Emacsen have deficiencies and/or bugs
|
|
|
189 which will adversely affect the performance and usability of
|
|
|
190 @code{cc-mode}.
|
|
|
191
|
|
|
192 @cindex @file{cc-mode-18.el} file
|
|
|
193 Similarly if you use the @file{cc-mode-18.el} compatibility file,
|
|
|
194 @file{cc-mode.el} will work with Emacs 18, but only moderately well. A
|
|
|
195 word of warning though, @emph{Emacs 18 lacks some fundamental
|
|
|
196 functionality and that ultimately means using Emacs 18 is a losing
|
|
|
197 battle}. Hence @code{cc-mode} under Emacs 18 is no longer supported and
|
|
|
198 it is highly recommended that you upgrade to Emacs 19. If you use
|
|
|
199 @code{cc-mode} under Emacs 18, you're on your own. With @code{cc-mode}
|
|
|
200 version 5, Emacs 18 support will be dropped altogether.
|
|
|
201
|
|
|
202 Note that as of XEmacs 19.13 and Emacs 19.30, your Emacs already comes
|
|
|
203 with @code{cc-mode} version 4 preconfigured for your use. You should be
|
|
|
204 able to safely skip the rest of the setup information in this chapter.
|
|
|
205
|
|
|
206 @cindex @file{.emacs} file
|
|
|
207 The first thing you will want to do is put @file{cc-mode.el} somewhere
|
|
|
208 on your @code{load-path} so Emacs can find it. Do a @kbd{C-h v
|
|
|
209 load-path RET} to see all the directories Emacs looks at when loading a
|
|
|
210 file. If none of these directories are appropriate, create a new
|
|
|
211 directory and add it to your @code{load-path}:
|
|
|
212
|
|
|
213 @noindent
|
|
|
214 @emph{[in the shell]}
|
|
|
215 @example
|
|
|
216 @group
|
|
|
217
|
|
|
218 % cd
|
|
|
219 % mkdir mylisp
|
|
|
220 % mv cc-mode.el mylisp
|
|
|
221 % cd mylisp
|
|
|
222
|
|
|
223 @end group
|
|
|
224 @end example
|
|
|
225
|
|
|
226 @noindent
|
|
|
227 @emph{[in your .emacs file add]}
|
|
|
228 @example
|
|
|
229
|
|
|
230 (setq load-path (cons "~/mylisp" load-path))
|
|
|
231
|
|
|
232 @end example
|
|
|
233
|
|
|
234 @cindex byte compile
|
|
|
235 Next you want to @dfn{byte compile} @file{cc-mode.el}. The mode uses a
|
|
|
236 lot of macros so if you don't byte compile it, things will be unbearably
|
|
|
237 slow. @emph{You can ignore all byte-compiler warnings!} They are the
|
|
|
238 result of the supporting different versions of Emacs, and none of the
|
|
|
239 warnings have any effect on operation. Let me say this again:
|
|
|
240 @strong{You really can ignore all byte-compiler warnings!}
|
|
|
241
|
|
|
242 Here's what to do to byte-compile the file [in emacs]:
|
|
|
243 @example
|
|
|
244
|
|
|
245 M-x byte-compile-file RET ~/mylisp/cc-mode.el RET
|
|
|
246
|
|
|
247 @end example
|
|
|
248
|
|
|
249 If you are running a version of Emacs or XEmacs that comes with
|
|
|
250 @code{cc-mode} by default, you can simply add the following to your
|
|
|
251 @file{.emacs} file in order to upgrade to the latest version of
|
|
|
252 @code{cc-mode}:
|
|
|
253 @example
|
|
|
254
|
|
|
255 (load "cc-mode")
|
|
|
256
|
|
|
257 @end example
|
|
|
258
|
|
|
259 Users of even older versions of Emacs 19, Emacs 18, or of the older
|
|
|
260 Lucid Emacs will probably be running an Emacs that has BOCM
|
|
|
261 @file{c-mode.el} and possible @file{c++-mode.el} pre-dumped. If your
|
|
|
262 Emacs is dumped with either of these files you first need to make Emacs
|
|
|
263 ``forget'' about those older modes.
|
|
|
264
|
|
|
265 If you can do a @kbd{C-h v c-mode-map RET} without getting an error, you
|
|
|
266 need to add these lines at the top of your @file{.emacs} file:
|
|
|
267 @example
|
|
|
268 @group
|
|
|
269
|
|
|
270 (fmakunbound 'c-mode)
|
|
|
271 (makunbound 'c-mode-map)
|
|
|
272 (fmakunbound 'c++-mode)
|
|
|
273 (makunbound 'c++-mode-map)
|
|
|
274 (makunbound 'c-style-alist)
|
|
|
275
|
|
|
276 @end group
|
|
|
277 @end example
|
|
|
278
|
|
|
279 After those lines you will want to add the following autoloads to your
|
|
|
280 @file{.emacs} file so that @code{cc-mode} gets loaded at the right time:
|
|
|
281 @example
|
|
|
282 @group
|
|
|
283
|
|
|
284 (autoload 'c++-mode "cc-mode" "C++ Editing Mode" t)
|
|
|
285 (autoload 'c-mode "cc-mode" "C Editing Mode" t)
|
|
|
286 (autoload 'objc-mode "cc-mode" "Objective-C Editing Mode" t)
|
|
|
287 (autoload 'java-mode "cc-mode" "Java Editing Mode" t)
|
|
|
288
|
|
|
289 @end group
|
|
|
290 @end example
|
|
|
291
|
|
|
292 Alternatively, if you want to make sure @code{cc-mode} is loaded when
|
|
|
293 Emacs starts up, you could use this line instead of the three autoloads
|
|
|
294 above:
|
|
|
295 @example
|
|
|
296
|
|
|
297 (require 'cc-mode)
|
|
|
298
|
|
|
299 @end example
|
|
|
300
|
|
|
301 Next, you will want to set up Emacs so that it edits C files in
|
|
|
302 @code{c-mode}, C++ files in @code{c++-mode}, and Objective-C files in
|
|
|
303 @code{objc-mode}. All users should add the following to their
|
|
|
304 @file{.emacs} file. Note that this assumes you'll be editing @code{.h}
|
|
|
305 and @code{.c} files as C, @code{.hh}, @code{.cc}, @code{.H}, and
|
|
|
306 @code{.C} files as C++, @code{.m} files as Objective-C, and @code{.java}
|
|
|
307 files as Java code. YMMV:
|
|
|
308 @example
|
|
|
309 @group
|
|
|
310
|
|
|
311 (setq auto-mode-alist
|
|
|
312 (append
|
|
|
313 '(("\\.C$" . c++-mode)
|
|
|
314 ("\\.H$" . c++-mode)
|
|
|
315 ("\\.cc$" . c++-mode)
|
|
|
316 ("\\.hh$" . c++-mode)
|
|
|
317 ("\\.c$" . c-mode)
|
|
|
318 ("\\.h$" . c-mode)
|
|
|
319 ("\\.m$" . objc-mode)
|
|
|
320 ("\\.java$" . java-mode)
|
|
|
321 ) auto-mode-alist))
|
|
|
322
|
|
|
323 @end group
|
|
|
324 @end example
|
|
|
325
|
|
|
326 You may already have some or all of these settings on your
|
|
|
327 @code{auto-mode-alist}, but it won't hurt to put them on there again.
|
|
|
328
|
|
|
329 That's all you need -- I know, I know, it sounds like a lot @code{:-)},
|
|
|
330 but after you've done all this, you should only need to quit and restart
|
|
|
331 Emacs. The next time you visit a C, C++, Objective-C, or Java file you
|
|
|
332 should be using @code{cc-mode}. You can check this easily by hitting
|
|
|
333 @kbd{M-x c-version RET} in the @code{c-mode}, @code{c++-mode}, or
|
|
|
334 @code{objc-mode} buffer. You should see this message in the echo area:
|
|
|
335 @example
|
|
|
336
|
|
|
337 Using @code{cc-mode} version 4.@var{xxx}
|
|
|
338
|
|
|
339 Where @var{xxx} is the latest release minor number.
|
|
|
340
|
|
|
341 @end example
|
|
|
342
|
|
|
343 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
344
|
|
|
345 @menu
|
|
|
346 * Syntactic Analysis::
|
|
|
347 * Indentation Calculation::
|
|
|
348 @end menu
|
|
|
349
|
|
|
350 @node New Indentation Engine, Minor Modes, Getting Connected, Top
|
|
|
351 @comment node-name, next, previous,up
|
|
|
352
|
|
|
353 @chapter New Indentation Engine
|
|
|
354 @cindex New Indentation Engine
|
|
|
355
|
|
|
356 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
357
|
|
|
358 @code{cc-mode} has a new indentation engine, providing a simplified, yet
|
|
|
359 flexible and general mechanism for customizing indentation. It breaks
|
|
|
360 indentation calculation into two steps. First for the line of code being
|
|
|
361 indented, @code{cc-mode} analyzes what kind of language construct it's
|
|
|
362 looking at, then it applies user defined offsets to the current line
|
|
|
363 based on this analysis.
|
|
|
364
|
|
|
365 This section will briefly cover how indentation is calculated in
|
|
|
366 @code{cc-mode}. It is important to understand the indentation model
|
|
|
367 being used so that you will know how to customize @code{cc-mode} for
|
|
|
368 your personal coding style.
|
|
|
369
|
|
|
370 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
371 @menu
|
|
|
372 * Syntactic Analysis::
|
|
|
373 * Indentation Calculation::
|
|
|
374 @end menu
|
|
|
375 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
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
|
|
|
391 The first thing @code{cc-mode} does when indenting a line of code, is to
|
|
|
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
|
|
|
410 It might help to see an example. Suppose we had the following code as
|
|
|
411 the only thing in a @code{c++-mode} buffer @footnote{The line numbers in
|
|
|
412 this and future examples don't actually appear in the buffer, of course!}:
|
|
|
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
|
|
|
432 line 4 this example, we'd see in the echo area:
|
|
|
433 @example
|
|
|
434
|
|
|
435 ((statement . 35))
|
|
|
436
|
|
|
437 @end example
|
|
|
438
|
|
|
439 This tells us that the line is a statement and it is indented relative
|
|
|
440 to buffer position 35, which happens to be the @samp{i} in @code{int} on
|
|
|
441 line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you
|
|
|
442 would see:
|
|
|
443 @example
|
|
|
444
|
|
|
445 ((defun-block-intro . 29))
|
|
|
446
|
|
|
447 @end example
|
|
|
448
|
|
|
449 This indicates that the @samp{int} line is the first statement in a top
|
|
|
450 level function block, and is indented relative to buffer position 29,
|
|
|
451 which is the brace just after the function header.
|
|
|
452
|
|
|
453 Here's another example:
|
|
|
454 @example
|
|
|
455 @group
|
|
|
456
|
|
|
457 1: int add( int val, int incr, int doit )
|
|
|
458 2: @{
|
|
|
459 3: if( doit )
|
|
|
460 4: @{
|
|
|
461 5: return( val + incr );
|
|
|
462 6: @}
|
|
|
463 7: return( val );
|
|
|
464 8: @}
|
|
|
465
|
|
|
466 @end group
|
|
|
467 @end example
|
|
|
468
|
|
|
469 @noindent
|
|
|
470 Hitting @kbd{C-c C-s} on line 4 gives us:
|
|
|
471 @example
|
|
|
472
|
|
|
473 ((substatement-open . 46))
|
|
|
474
|
|
|
475 @end example
|
|
|
476
|
|
|
477 @cindex substatement
|
|
|
478 @cindex substatment block
|
|
|
479 @noindent
|
|
|
480 which tells us that this is a brace that @emph{opens} a substatement
|
|
|
481 block. @footnote{A @dfn{substatement} indicates the line after an
|
|
|
482 @code{if}, @code{else}, @code{while}, @code{do}, @code{switch}, or
|
|
|
483 @code{for} statement, and a @dfn{substatement block} is a brace block
|
|
|
484 following one of those constructs.}
|
|
|
485
|
|
|
486 @cindex comment only line
|
|
|
487 Syntactic component lists can contain more than one component, and
|
|
|
488 individual syntactic components need not have relative buffer positions.
|
|
|
489 The most common example of this is a line that contains a @dfn{comment
|
|
|
490 only line}.
|
|
|
491 @example
|
|
|
492 @group
|
|
|
493
|
|
|
494 1: void draw_list( List<Drawables>& drawables )
|
|
|
495 2: @{
|
|
|
496 3: // call the virtual draw() method on each element in list
|
|
|
497 4: for( int i=0; i < drawables.count(), ++i )
|
|
|
498 5: @{
|
|
|
499 6: drawables[i].draw();
|
|
|
500 7: @}
|
|
|
501 8: @}
|
|
|
502
|
|
|
503 @end group
|
|
|
504 @end example
|
|
|
505
|
|
|
506 @noindent
|
|
|
507 Hitting @kbd{C-c C-s} on line 3 of example 3 gives us:
|
|
|
508 @example
|
|
|
509
|
|
|
510 ((comment-intro) (defun-block-intro . 46))
|
|
|
511
|
|
|
512 @end example
|
|
|
513
|
|
|
514 @noindent
|
|
|
515 so you can see that the syntactic component list contains two syntactic
|
|
|
516 components. Also notice that the first component,
|
|
|
517 @samp{(comment-intro)} has no relative buffer position.
|
|
|
518
|
|
|
519
|
|
|
520 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
521 @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
|
|
|
522 @comment node-name, next, previous,up
|
|
|
523 @section Indentation Calculation
|
|
|
524 @cindex Indentation Calculation
|
|
|
525 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
526
|
|
|
527 @vindex c-offsets-alist
|
|
|
528 @vindex offsets-alist (c-)
|
|
|
529 Indentation for the current line is calculated using the syntactic
|
|
|
530 component list derived in step 1 above (see @ref{Syntactic Analysis}).
|
|
|
531 Each component contributes to the final total indentation of the line in
|
|
|
532 two ways.
|
|
|
533
|
|
|
534 First, the syntactic symbols are looked up in the @code{c-offsets-alist}
|
|
|
535 variable, which is an association list of syntactic symbols and the
|
|
|
536 offsets to apply for those symbols. These offsets are added to the
|
|
|
537 running total.
|
|
|
538
|
|
|
539 Second, if the component has a relative buffer position, @code{cc-mode}
|
|
|
540 adds the column number of that position to the running total. By adding
|
|
|
541 up the offsets and columns for every syntactic component on the list,
|
|
|
542 the final total indentation for the current line is computed.
|
|
|
543
|
|
|
544 Let's use our two code examples above to see how this works. Here is
|
|
|
545 our first example again:
|
|
|
546 @example
|
|
|
547 @group
|
|
|
548
|
|
|
549 1: void swap( int& a, int& b )
|
|
|
550 2: @{
|
|
|
551 3: int tmp = a;
|
|
|
552 4: a = b;
|
|
|
553 5: b = tmp;
|
|
|
554 6: @}
|
|
|
555
|
|
|
556 @end group
|
|
|
557 @end example
|
|
|
558
|
|
|
559 @kindex TAB
|
|
|
560 Let's say point is on line 3 and we hit the @key{TAB} key to re-indent
|
|
|
561 the line. Remember that the syntactic component list for that
|
|
|
562 line is:
|
|
|
563 @example
|
|
|
564
|
|
|
565 ((defun-block-intro . 29))
|
|
|
566
|
|
|
567 @end example
|
|
|
568
|
|
|
569 @noindent
|
|
|
570 @code{cc-mode} looks up @code{defun-block-intro} in the
|
|
|
571 @code{c-offsets-alist} variable. Let's say it finds the value @samp{4};
|
|
|
572 it adds this to the running total (initialized to zero), yielding a
|
|
|
573 running total indentation of 4 spaces.
|
|
|
574
|
|
|
575 Next @code{cc-mode} goes to buffer position 29 and asks for the current
|
|
|
576 column. Since the brace at buffer position 29 is in column zero, it
|
|
|
577 adds @samp{0} to the running total. Since there is only one syntactic
|
|
|
578 component on the list for this line, indentation calculation is
|
|
|
579 complete, and the total indentation for the line
|
|
|
580 is 4 spaces.
|
|
|
581
|
|
|
582 Here's another example:
|
|
|
583 @example
|
|
|
584 @group
|
|
|
585
|
|
|
586 1: int add( int val, int incr, int doit )
|
|
|
587 2: @{
|
|
|
588 3: if( doit )
|
|
|
589 4: @{
|
|
|
590 5: return( val + incr );
|
|
|
591 6: @}
|
|
|
592 7: return( val );
|
|
|
593 8: @}
|
|
|
594
|
|
|
595 @end group
|
|
|
596 @end example
|
|
|
597
|
|
|
598 If we were to hit @kbd{TAB} on line 4 in the above example, the same
|
|
|
599 basic process is performed, despite the differences in the syntactic
|
|
|
600 component list. Remember that the list for this line is:
|
|
|
601 @example
|
|
|
602
|
|
|
603 ((substatement-open . 46))
|
|
|
604
|
|
|
605 @end example
|
|
|
606
|
|
|
607 Here, @code{cc-mode} first looks up the @code{substatement-open} symbol
|
|
|
608 in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This
|
|
|
609 yields a running total of 4. @code{cc-mode} then goes to
|
|
|
610 buffer position 46, which is the @samp{i} in @code{if} on line 3. This
|
|
|
611 character is in the fourth column on that line so adding this to the
|
|
|
612 running total yields an indentation for the line of 8 spaces.
|
|
|
613
|
|
|
614 Simple, huh?
|
|
|
615
|
|
|
616 Actually, the mode usually just does The Right Thing without you having
|
|
|
617 to think about it in this much detail. But when customizing
|
|
|
618 indentation, it's helpful to understand the general indentation model
|
|
|
619 being used.
|
|
|
620
|
|
|
621 @vindex c-echo-syntactic-information-p
|
|
|
622 @vindex echo-syntactic-information-p (c-)
|
|
|
623 @cindex TAB
|
|
|
624 To help you configure @code{cc-mode}, you can set the variable
|
|
|
625 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
|
|
|
626 syntactic component list and calculated offset will always be echoed in
|
|
|
627 the minibuffer when you hit @kbd{TAB}.
|
|
|
628
|
|
|
629
|
|
|
630 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
631 @node Minor Modes, Indentation Commands, New Indentation Engine, Top
|
|
|
632 @comment node-name, next, previous,up
|
|
|
633
|
|
|
634 @chapter Minor Modes
|
|
|
635 @cindex Minor Modes
|
|
|
636 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
637
|
|
|
638 @code{cc-mode} contains two minor-mode-like features that you should
|
|
|
639 find useful while you enter new C code. The first is called
|
|
|
640 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
|
|
|
641 mode. These minor modes can be toggled on and off independently, and
|
|
|
642 @code{cc-mode} can be configured so that it comes up with any
|
|
|
643 combination of these minor modes. By default, both of these minor modes
|
|
|
644 are turned off.
|
|
|
645
|
|
|
646 The state of the minor modes is always reflected in the minor mode list
|
|
|
647 on the modeline of the @code{cc-mode} buffer. When auto-newline mode is
|
|
|
648 enabled, you will see @samp{C/a} on the mode line @footnote{Remember
|
|
|
649 that the @samp{C} would be replaced with @samp{C++} or @samp{ObjC} if
|
|
|
650 you were editing C++ or Objective-C code.}. When hungry delete mode is
|
|
|
651 enabled you would see @samp{C/h} and when both modes are enabled, you'd
|
|
|
652 see @samp{C/ah}.
|
|
|
653
|
|
|
654 @kindex C-c C-a
|
|
|
655 @kindex C-c C-d
|
|
|
656 @kindex C-c C-t
|
|
|
657 @findex c-toggle-hungry-state
|
|
|
658 @findex c-toggle-auto-state
|
|
|
659 @findex c-toggle-auto-hungry-state
|
|
|
660 @findex toggle-hungry-state (c-)
|
|
|
661 @findex toggle-auto-state (c-)
|
|
|
662 @findex toggle-auto-hungry-state (c-)
|
|
|
663 @code{cc-mode} provides keybindings which allow you to toggle the minor
|
|
|
664 modes while editing code on the fly. To toggle just the auto-newline
|
|
|
665 state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do
|
|
|
666 this, you should see the @samp{a} indicator either appear or disappear
|
|
|
667 on the modeline. Similarly, to toggle just the hungry-delete state, use
|
|
|
668 @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states
|
|
|
669 together, use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
|
|
|
670
|
|
|
671 To set up the auto-newline and hungry-delete states to your preferred
|
|
|
672 values, you would need to add some lisp to your @file{.emacs} file that
|
|
|
673 called one of the @code{c-toggle-*-state} functions directly. When
|
|
|
674 called programmatically, each function takes a numeric value, where
|
|
|
675 a positive number enables the minor mode, a negative number disables the
|
|
|
676 mode, and zero toggles the current state of the mode.
|
|
|
677
|
|
|
678 So for example, if you wanted to enable both auto-newline and
|
|
|
679 hungry-delete for all your C file editing, you could add the following
|
|
|
680 to your @file{.emacs} file:
|
|
|
681 @example
|
|
|
682
|
|
|
683 (add-hook 'c-mode-common-hook '(lambda () (c-toggle-auto-hungry-state 1)))
|
|
|
684
|
|
|
685 @end example
|
|
|
686
|
|
|
687
|
|
|
688 @cindex electric characters
|
|
|
689
|
|
|
690 @menu
|
|
|
691 * Auto-newline insertion::
|
|
|
692 * Hungry-deletion of whitespace::
|
|
|
693 @end menu
|
|
|
694
|
|
|
695 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
696 @node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes
|
|
|
697 @comment node-name, next, previous,up
|
|
|
698
|
|
|
699 @section Auto-newline insertion
|
|
|
700 @cindex Auto-newline insertion
|
|
|
701 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
702
|
|
|
703 @cindex electric commands
|
|
|
704 Auto-newline minor mode works by enabling certain @dfn{electric
|
|
|
705 commands}. Electric commands are typically bound to special characters
|
|
|
706 such as the left and right braces, colons, semi-colons, etc., which when
|
|
|
707 typed, perform some magic formatting in addition to inserting the typed
|
|
|
708 character. As a general rule, electric commands are only electric when
|
|
|
709 the following conditions apply:
|
|
|
710
|
|
|
711 @itemize @bullet
|
|
|
712 @item
|
|
|
713 Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
|
|
|
714 @samp{C/ah} indicator on the modeline.
|
|
|
715
|
|
|
716 @cindex literal
|
|
|
717 @cindex syntactic whitespace
|
|
|
718 @item
|
|
|
719 The character was not typed inside of a literal @footnote{A
|
|
|
720 @dfn{literal} is defined in @code{cc-mode} as any comment,
|
|
|
721 string, or cpp macro definition. These constructs are also known as
|
|
|
722 @dfn{syntactic whitespace} since they are usually ignored when scanning
|
|
|
723 C code.}.
|
|
|
724
|
|
|
725 @item
|
|
|
726 @kindex C-u
|
|
|
727 No numeric argument was supplied to the command (i.e. it was typed as
|
|
|
728 normal, with no @kbd{C-u} prefix).
|
|
|
729
|
|
|
730 @end itemize
|
|
|
731
|
|
|
732 Certain other conditions may apply on a language specific basis. For
|
|
|
733 example, the second slash (@kbd{/}) of a C++ style line comment is
|
|
|
734 electric in @code{c++-mode}, @code{objc-mode}, and @code{java-mode}, but
|
|
|
735 not in @code{c-mode}.
|
|
|
736
|
|
|
737
|
|
|
738 @menu
|
|
|
739 * Hanging Braces::
|
|
|
740 * Hanging Colons::
|
|
|
741 * Hanging Semi-colons and commas::
|
|
|
742 * Other electric commands::
|
|
|
743 * Clean-ups::
|
|
|
744 @end menu
|
|
|
745
|
|
|
746 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
747 @node Hanging Braces, Hanging Colons, , Auto-newline insertion
|
|
|
748 @comment node-name, next, previous,up
|
|
|
749
|
|
|
750 @subsection Hanging Braces
|
|
|
751 @cindex Hanging Braces
|
|
|
752 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
753
|
|
|
754 @findex c-electric-brace
|
|
|
755 @findex electric-brace (c-)
|
|
|
756 @vindex c-hanging-braces-alist
|
|
|
757 @vindex hanging-braces-alist (c-)
|
|
|
758 @vindex c-offsets-alist
|
|
|
759 @vindex offsets-alist (c-)
|
|
|
760 When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),
|
|
|
761 the electric command @code{c-electric-brace} gets run. This command has
|
|
|
762 two electric formatting behaviors. First, it will perform some
|
|
|
763 re-indentation of the line the brace was typed on, and second, it will
|
|
|
764 add various newlines before and/or after the typed brace.
|
|
|
765 Re-indentation occurs automatically whenever the electric behavior is
|
|
|
766 enabled. If the brace ends up on a line other than the one it was typed
|
|
|
767 on, then that line is on is also indented according to
|
|
|
768 @code{c-offsets-alist}.
|
|
|
769
|
|
|
770 @cindex class-open syntactic symbol
|
|
|
771 @cindex class-close syntactic symbol
|
|
|
772 @cindex defun-open syntactic symbol
|
|
|
773 @cindex defun-close syntactic symbol
|
|
|
774 @cindex inline-open syntactic symbol
|
|
|
775 @cindex inline-close syntactic symbol
|
|
|
776 @cindex brace-list-open syntactic symbol
|
|
|
777 @cindex brace-list-close syntactic symbol
|
|
|
778 @cindex brace-list-intro syntactic symbol
|
|
|
779 @cindex brace-list-entry syntactic symbol
|
|
|
780 @cindex block-open syntactic symbol
|
|
|
781 @cindex block-close syntactic symbol
|
|
|
782 @cindex substatement-open syntactic symbol
|
|
|
783 @cindex statement-case-open syntactic symbol
|
|
|
784
|
|
|
785 The insertion of newlines is controlled by the
|
|
|
786 @code{c-hanging-braces-alist} variable. This variable contains a
|
|
|
787 mapping between syntactic symbols related to braces, and a list of
|
|
|
788 places to insert a newline. The syntactic symbols that are useful for
|
|
|
789 this list are: @code{class-open}, @code{class-close}, @code{defun-open},
|
|
|
790 @code{defun-close}, @code{inline-open}, @code{inline-close},
|
|
|
791 @code{brace-list-open}, @code{brace-list-close},
|
|
|
792 @code{brace-list-intro}, @code{brace-list-entry}, @code{block-open},
|
|
|
793 @code{block-close}, @code{substatement-open}, and
|
|
|
794 @code{statement-case-open}. @xref{Syntactic Symbols} for a more
|
|
|
795 detailed description of these syntactic symbols.
|
|
|
796
|
|
|
797 @cindex custom indentation function
|
|
|
798 The value associated with each syntactic symbol in this association list
|
|
|
799 is called an @var{ACTION} which can be either a function or a list.
|
|
|
800 @xref{Custom Brace and Colon Hanging} for a more detailed discussion of
|
|
|
801 using a function as a brace hanging @var{ACTION}.
|
|
|
802
|
|
|
803 When @var{ACTION} is a list, it can contain any combination of the
|
|
|
804 symbols @code{before} or @code{after}, directing @code{cc-mode} where to
|
|
|
805 put newlines in relationship to the brace being inserted. Thus, if the
|
|
|
806 list contains only the symbol @code{after}, then the brace is said to
|
|
|
807 @dfn{hang} on the right side of the line, as in:
|
|
|
808 @example
|
|
|
809 @group
|
|
|
810
|
|
|
811 // here, open braces always `hang'
|
|
|
812 void spam( int i ) @{
|
|
|
813 if( i == 7 ) @{
|
|
|
814 dosomething(i);
|
|
|
815 @}
|
|
|
816 @}
|
|
|
817
|
|
|
818
|
|
|
819 @end group
|
|
|
820 @end example
|
|
|
821
|
|
|
822 When the list contains both @code{after} and @code{before}, the braces
|
|
|
823 will appear on a line by themselves, as shown by the close braces in the
|
|
|
824 above example. The list can also be empty, in which case no newlines
|
|
|
825 are added either before or after the brace.
|
|
|
826
|
|
|
827 For example, the default value of @code{c-hanging-braces-alist} is:
|
|
|
828 @example
|
|
|
829 @group
|
|
|
830
|
|
|
831 (defvar c-hanging-braces-alist '((brace-list-open)
|
|
|
832 (substatement-open after)
|
|
|
833 (block-close . c-snug-do-while)))
|
|
|
834
|
|
|
835 @end group
|
|
|
836 @end example
|
|
|
837
|
|
|
838 @noindent
|
|
|
839 which says that @code{brace-list-open} braces should both hang on the
|
|
|
840 right side, and allow subsequent text to follow on the same line as the
|
|
|
841 brace. Also, @code{substatement-open} braces should hang on the right
|
|
|
842 side, but subsequent text should follow on the next line. Here, in the
|
|
|
843 @code{block-close} entry, you also see an example of using a function as
|
|
|
844 an @var{ACTION}.
|
|
|
845
|
|
|
846
|
|
|
847 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
848 @node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion
|
|
|
849 @comment node-name, next, previous,up
|
|
|
850
|
|
|
851 @subsection Hanging Colons
|
|
|
852 @cindex Hanging Colons
|
|
|
853 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
854
|
|
|
855 @vindex hanging-colons-alist (c-)
|
|
|
856 @vindex c-hanging-colons-alist
|
|
|
857 Using a mechanism similar to brace hanging (see @ref{Hanging Braces}),
|
|
|
858 colons can also be made to hang using the variable
|
|
|
859 @code{c-hanging-colons-alist}. The syntactic symbols appropriate for
|
|
|
860 this assocation list are: @code{case-label}, @code{label},
|
|
|
861 @code{access-label}, @code{member-init-intro}, and @code{inher-intro}.
|
|
|
862 @xref{Hanging Braces} and @ref{Custom Brace and Colon Hanging} for
|
|
|
863 details. Note however, that @code{c-hanging-colons-alist} does not
|
|
|
864 implement functions as @var{ACTION}s.
|
|
|
865
|
|
|
866 @cindex clean-ups
|
|
|
867 In C++, double-colons are used as a scope operator but because these
|
|
|
868 colons always appear right next to each other, newlines before and after
|
|
|
869 them are controlled by a different mechanism, called @dfn{clean-ups} in
|
|
|
870 @code{cc-mode}. @xref{Clean-ups} for details.
|
|
|
871
|
|
|
872
|
|
|
873 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
874 @node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion
|
|
|
875 @comment node-name, next, previous,up
|
|
|
876
|
|
|
877 @subsection Hanging Semi-colons and commas
|
|
|
878 @cindex Hanging Semi-colons and commas
|
|
|
879 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
880
|
|
|
881 Semicolons and commas are also electric in @code{cc-mode}, but since
|
|
|
882 these characters do not correspond directly to syntactic symbols, a
|
|
|
883 different mechanism is used to determine whether newlines should be
|
|
|
884 automatically inserted after these characters. @xref{Customizing
|
|
|
885 Semi-colons and Commas} for details.
|
|
|
886
|
|
|
887
|
|
|
888 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
889 @node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion
|
|
|
890 @comment node-name, next, previous,up
|
|
|
891
|
|
|
892 @subsection Other electric commands
|
|
|
893 @cindex Other electric commands
|
|
|
894 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
895
|
|
|
896 @kindex #
|
|
|
897 @findex c-electric-pound
|
|
|
898 @vindex c-electric-pound-behavior
|
|
|
899 @findex electric-pound (c-)
|
|
|
900 @vindex electric-pound-behavior (c-)
|
|
|
901 @vindex c-offsets-alist
|
|
|
902 @vindex offsets-alist (c-)
|
|
|
903 A few other keys also provide electric behavior. For example the
|
|
|
904 @kbd{#} key (@code{c-electric-pound}) is electric when it is typed as
|
|
|
905 the first non-whitespace character on a line. In this case, the
|
|
|
906 variable @code{c-electric-pound-behavior} is consulted for the electric
|
|
|
907 behavior. This variable takes a list value, although the only element
|
|
|
908 currently defined is @code{alignleft}, which tells this command to force
|
|
|
909 the @samp{#} character into column zero. This is useful for entering
|
|
|
910 cpp macro definitions.
|
|
|
911
|
|
|
912 @findex c-electric-star
|
|
|
913 @findex c-electric-slash
|
|
|
914 @findex electric-star (c-)
|
|
|
915 @findex electric-slash (c-)
|
|
|
916 @cindex comment-only line
|
|
|
917 Stars and slashes (i.e. @kbd{*} and @kbd{/}) are also electric under
|
|
|
918 certain circumstances. If a star is inserted as the second character of
|
|
|
919 a C style block comment on a @dfn{comment-only} line, then the comment
|
|
|
920 delimiter is indented as defined by @code{c-offsets-alist}. A
|
|
|
921 comment-only line is defined as a line which contains only a comment, as
|
|
|
922 in:
|
|
|
923 @example
|
|
|
924 @group
|
|
|
925
|
|
|
926 void spam( int i )
|
|
|
927 @{
|
|
|
928 // this is a comment-only line...
|
|
|
929 if( i == 7 ) // but this is not
|
|
|
930 @{
|
|
|
931 dosomething(i);
|
|
|
932 @}
|
|
|
933 @}
|
|
|
934
|
|
|
935 @end group
|
|
|
936 @end example
|
|
|
937
|
|
|
938 Likewise, if a slash is inserted as the second slash in a C++ style line
|
|
|
939 comment (also only on a comment-only line), then the line is indented as
|
|
|
940 defined by @code{c-offsets-alist}.
|
|
|
941
|
|
|
942
|
|
|
943 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
944 @node Clean-ups, , Other electric commands, Auto-newline insertion
|
|
|
945 @comment node-name, next, previous,up
|
|
|
946
|
|
|
947 @subsection Clean-ups
|
|
|
948 @cindex Clean-ups
|
|
|
949 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
950
|
|
|
951 @dfn{Clean-ups} are a mechanism complementary to colon and brace
|
|
|
952 hanging. On the surface, it would seem that clean-ups overlap the
|
|
|
953 functionality provided by the @code{c-hanging-*-alist} variables, and
|
|
|
954 similarly, clean-ups are only enabled when auto-newline minor mode is
|
|
|
955 enabled. Clean-ups are used however to adjust code ``after-the-fact'',
|
|
|
956 i.e. to eliminate some whitespace that isn't inserted by electric
|
|
|
957 commands, or whitespace that contains intervening constructs.
|
|
|
958
|
|
|
959 @cindex literal
|
|
|
960 You can configure @code{cc-mode}'s clean-ups by setting the variable
|
|
|
961 @code{c-cleanup-list}, which is a list of clean-up symbols. By default,
|
|
|
962 @code{cc-mode} cleans up only the @code{scope-operator} construct, which
|
|
|
963 is necessary for proper C++ support. Note that clean-ups are only
|
|
|
964 performed when the construct does not occur within a literal (see
|
|
|
965 @ref{Auto-newline insertion}), and when there is nothing but whitespace
|
|
|
966 appearing between the individual components of the construct.
|
|
|
967
|
|
|
968 @vindex c-cleanup-list
|
|
|
969 @vindex cleanup-list (c-)
|
|
|
970 There are currently only five specific constructs that @code{cc-mode}
|
|
|
971 can clean up, as indicated by these symbols:
|
|
|
972
|
|
|
973 @itemize @bullet
|
|
|
974 @item
|
|
|
975 @code{brace-else-brace} -- cleans up @samp{@} else @{} constructs by
|
|
|
976 placing the entire construct on a single line. Clean-up occurs when the
|
|
|
977 open brace after the @samp{else} is typed. So for example, this:
|
|
|
978 @example
|
|
|
979 @group
|
|
|
980
|
|
|
981 void spam(int i)
|
|
|
982 @{
|
|
|
983 if( i==7 )
|
|
|
984 @{
|
|
|
985 dosomething();
|
|
|
986 @}
|
|
|
987 else
|
|
|
988 @{
|
|
|
989
|
|
|
990 @end group
|
|
|
991 @end example
|
|
|
992 @noindent
|
|
|
993 appears like this after the open brace is typed:
|
|
|
994 @example
|
|
|
995 @group
|
|
|
996
|
|
|
997 void spam(int i)
|
|
|
998 @{
|
|
|
999 if( i==7 ) @{
|
|
|
1000 dosomething();
|
|
|
1001 @} else @{
|
|
|
1002
|
|
|
1003 @end group
|
|
|
1004 @end example
|
|
|
1005
|
|
|
1006 @item
|
|
|
1007 @code{empty-defun-braces} -- cleans up braces following a top-level
|
|
|
1008 function or class definition that contains no body. Clean up occurs
|
|
|
1009 when the closing brace is typed. Thus the following:
|
|
|
1010 @example
|
|
|
1011 @group
|
|
|
1012
|
|
|
1013 class Spam
|
|
|
1014 @{
|
|
|
1015 @}
|
|
|
1016
|
|
|
1017 @end group
|
|
|
1018 @end example
|
|
|
1019 @noindent
|
|
|
1020 is transformed into this when the close brace is typed:
|
|
|
1021 @example
|
|
|
1022 @group
|
|
|
1023
|
|
|
1024 class Spam
|
|
|
1025 @{@}
|
|
|
1026
|
|
|
1027 @end group
|
|
|
1028 @end example
|
|
|
1029
|
|
|
1030 @item
|
|
|
1031 @code{defun-close-semi} -- cleans up the terminating semi-colon on
|
|
|
1032 top-level function or class definitions when they follow a close
|
|
|
1033 brace. Clean up occurs when the semi-colon is typed.
|
|
|
1034 So for example, the following:
|
|
|
1035 @example
|
|
|
1036 @group
|
|
|
1037
|
|
|
1038 class Spam
|
|
|
1039 @{
|
|
|
1040 @}
|
|
|
1041 ;
|
|
|
1042
|
|
|
1043 @end group
|
|
|
1044 @end example
|
|
|
1045 @noindent
|
|
|
1046 is transformed into this when the semi-colon is typed:
|
|
|
1047
|
|
|
1048 @example
|
|
|
1049 @group
|
|
|
1050
|
|
|
1051 class Spam
|
|
|
1052 @{
|
|
|
1053 @};
|
|
|
1054
|
|
|
1055 @end group
|
|
|
1056 @end example
|
|
|
1057
|
|
|
1058 @item
|
|
|
1059 @code{list-close-comma} -- cleans up commas following braces in array
|
|
|
1060 and aggregate initializers. Clean up occurs when the comma is typed.
|
|
|
1061
|
|
|
1062 @item
|
|
|
1063 @code{scope-operator} -- cleans up double colons which may designate a
|
|
|
1064 C++ scope operator split across multiple lines@footnote{Certain C++
|
|
|
1065 constructs introduce ambiguous situations, so @code{scope-operator}
|
|
|
1066 clean-ups may not always be correct. This usually only occurs when
|
|
|
1067 scoped identifiers appear in switch label tags.}. Clean up occurs when
|
|
|
1068 the second colon is typed. You will always want @code{scope-operator}
|
|
|
1069 in the @code{c-cleanup-list} when you are editing C++ code.
|
|
|
1070
|
|
|
1071 @end itemize
|
|
|
1072
|
|
|
1073
|
|
|
1074 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1075 @node Hungry-deletion of whitespace, , Auto-newline insertion, Minor Modes
|
|
|
1076 @comment node-name, next, previous,up
|
|
|
1077
|
|
|
1078 @section Hungry-deletion of whitespace
|
|
|
1079 @cindex Hungry-deletion of whitespace
|
|
|
1080 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1081
|
|
|
1082 Hungry deletion of whitespace, or as it more commonly called,
|
|
|
1083 @dfn{hungry-delete mode}, is a simple feature that some people find
|
|
|
1084 extremely useful. In fact, you might find yourself wanting
|
|
|
1085 hungry-delete in @strong{all} your editing modes!
|
|
|
1086
|
|
|
1087 @kindex DEL
|
|
|
1088 In a nutshell, when hungry-delete mode is enabled, hitting the @kbd{DEL}
|
|
|
1089 character will consume all preceding whitespace, including newlines and
|
|
|
1090 tabs. This can really cut down on the number of @kbd{DEL}'s you have to
|
|
|
1091 type if, for example you made a mistake on the preceding line.
|
|
|
1092
|
|
|
1093 @findex c-electric-delete
|
|
|
1094 @findex electric-delete (c-)
|
|
|
1095 @vindex c-delete-function
|
|
|
1096 @vindex delete-function (c-)
|
|
|
1097 @cindex literal
|
|
|
1098 By default, @code{cc-mode} actually runs the command
|
|
|
1099 @code{c-electric-delete} when you hit @kbd{DEL}. When this command is
|
|
|
1100 used to delete a single character (i.e. when it is called interactively
|
|
|
1101 with no numeric argument), it really runs the function contained in the
|
|
|
1102 variable @code{c-delete-function}. This function is called with a
|
|
|
1103 single argument, which is the number of characters to delete.
|
|
|
1104 @code{c-delete-function} is also called when the @kbd{DEL} key is typed
|
|
|
1105 inside a literal (see @ref{Auto-newline insertion}. Inside a literal,
|
|
|
1106 @code{c-electric-delete} is not electric, which is typical of all the
|
|
|
1107 so-called electric commands.
|
|
|
1108
|
|
|
1109
|
|
|
1110 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1111 @node Indentation Commands, Customizing Indentation, Minor Modes, Top
|
|
|
1112 @comment node-name, next, previous,up
|
|
|
1113
|
|
|
1114 @chapter Indentation Commands
|
|
|
1115 @cindex Indentation Commands
|
|
|
1116 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1117
|
|
|
1118 @findex c-set-style
|
|
|
1119 @findex set-style (c-)
|
|
|
1120 Various commands are provided which allow you to conveniently re-indent
|
|
|
1121 C constructs, and these are outlined below. There are several things to
|
|
|
1122 note about these indentation commands. First, when you
|
|
|
1123 change your programming style, either though @code{c-set-style} or some
|
|
|
1124 other means, your file does @emph{not} automatically get re-indented.
|
|
|
1125 When you change style parameters, you will typically need to reformat
|
|
|
1126 the line, expression, or buffer to see the effects of your changes.
|
|
|
1127
|
|
|
1128 @cindex c-hanging- functions
|
|
|
1129 @findex c-hanging-braces-alist
|
|
|
1130 @findex hanging-braces-alist (c-)
|
|
|
1131 Second, changing some variables have no effect on existing code, even
|
|
|
1132 when you do re-indent. For example, the @code{c-hanging-*} variables and
|
|
|
1133 @code{c-cleanup-list} only affect newly entered code. So for example,
|
|
|
1134 changing @code{c-hanging-braces-alist} and re-indenting the buffer will
|
|
|
1135 not adjust placement of braces already in the file.
|
|
|
1136
|
|
|
1137 @vindex c-progress-interval
|
|
|
1138 @vindex progress-interval (c-)
|
|
|
1139 Third, re-indenting large portions of code is currently rather
|
|
|
1140 inefficient. Improvements have been made since previous releases of
|
|
|
1141 @code{cc-mode}, and much more radical improvements will be made for the
|
|
|
1142 next release, but for now you need to be aware of this @footnote{In
|
|
|
1143 particular, I have had people complain about the speed that
|
|
|
1144 @code{cc-mode} re-indents @code{lex(1)} output. Lex, yacc, and other
|
|
|
1145 code generators usually output some pretty perverse code. @emph{Don't}
|
|
|
1146 try to indent this stuff with @code{cc-mode}!}. Some provision has been
|
|
|
1147 made to at least inform you as to the progress of your large
|
|
|
1148 re-indentation command. The variable @code{c-progress-interval}
|
|
|
1149 controls how often a progress message is displayed. Set this variable
|
|
|
1150 to @code{nil} to inhibit progress messages. Note that this feature only
|
|
|
1151 works with Emacs 19.
|
|
|
1152
|
|
|
1153 Also, except as noted below, re-indentation is always driven by the
|
|
|
1154 same mechanisms that control on-the-fly indentation of code. @xref{New
|
|
|
1155 Indentation Engine} for details.
|
|
|
1156
|
|
|
1157 @findex c-indent-command
|
|
|
1158 @findex indent-command (c-)
|
|
|
1159 @vindex c-tab-always-indent
|
|
|
1160 @vindex tab-always-indent (c-)
|
|
|
1161 @kindex TAB
|
|
|
1162 @cindex literal
|
|
|
1163 To indent a single line of code, use @kbd{TAB}
|
|
|
1164 (@code{c-indent-command}). The behavior of this command is controlled
|
|
|
1165 by the variable @code{c-tab-always-indent}. When this variable is
|
|
|
1166 @code{t}, @kbd{TAB} always just indents the current line. When
|
|
|
1167 @code{nil}, the line is indented only if point is at the left
|
|
|
1168 margin, or on or before the first non-whitespace character on the line,
|
|
|
1169 otherwise a real tab character is inserted. If this variable's value is
|
|
|
1170 something other that @code{t} or @code{nil} (e.g. @code{'other}), then a
|
|
|
1171 real tab character is inserted only when point is inside a
|
|
|
1172 literal (see @ref{Auto-newline insertion}), otherwise the line is
|
|
|
1173 indented.
|
|
|
1174
|
|
|
1175 @kindex M-C-q
|
|
|
1176 @findex c-indent-exp
|
|
|
1177 @findex indent-exp (c-)
|
|
|
1178 To indent an entire balanced brace or parenthesis expression, use
|
|
|
1179 @kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on
|
|
|
1180 the opening brace or parenthesis of the expression you want to indent.
|
|
|
1181
|
|
|
1182 @kindex C-c C-q
|
|
|
1183 @findex c-indent-defun
|
|
|
1184 @findex indent-defun (c-)
|
|
|
1185 Another very convenient keystroke is @kbd{C-c C-q}
|
|
|
1186 (@code{c-indent-defun}) when re-indents the entire top-level function or
|
|
|
1187 class definition that encompases point. It leaves point at the
|
|
|
1188 same position within the buffer.
|
|
|
1189
|
|
|
1190 @kindex M-C-\
|
|
|
1191 @findex indent-region
|
|
|
1192 To indent any arbitrary region of code, use @kbd{M-C-\}
|
|
|
1193 (@code{indent-region}). This is a standard Emacs command, specially
|
|
|
1194 tailored for C code in a @code{cc-mode} buffer. Note that of course,
|
|
|
1195 point and mark must delineate the region you
|
|
|
1196 want to indent.
|
|
|
1197
|
|
|
1198 @kindex M-C-h
|
|
|
1199 @findex c-mark-function
|
|
|
1200 @findex mark-function (c-)
|
|
|
1201 While not strictly an indentation function, @kbd{M-C-h}
|
|
|
1202 (@code{c-mark-function}) is useful for marking the current top-level
|
|
|
1203 function or class definition as the current region.
|
|
|
1204
|
|
|
1205
|
|
|
1206 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1207 @node Customizing Indentation, Syntactic Symbols, Indentation Commands, Top
|
|
|
1208 @comment node-name, next, previous,up
|
|
|
1209
|
|
|
1210 @chapter Customizing Indentation
|
|
|
1211 @cindex Customizing Indentation
|
|
|
1212 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1213
|
|
|
1214 @cindex c-set-offset
|
|
|
1215 @cindex set-offset (c-)
|
|
|
1216 The @code{c-offsets-alist} variable is where you customize all your
|
|
|
1217 indentations. You simply need to decide what additional offset you want
|
|
|
1218 to add for every syntactic symbol. You can use the command @kbd{C-c
|
|
|
1219 C-o} (@code{c-set-offset}) as the way to set offsets, both interactively
|
|
|
1220 and from your mode hook. Also, you can set up @emph{styles} of
|
|
|
1221 indentation just like in BOCM. Most likely, you'll
|
|
|
1222 find one of the pre-defined styles will suit your needs, but if not,
|
|
|
1223 this section will describe how to set up basic editing configurations.
|
|
|
1224 @xref{Styles} for an explanation of how to set up named styles.
|
|
|
1225
|
|
|
1226 @cindex c-basic-offset
|
|
|
1227 @cindex basic-offset (c-)
|
|
|
1228 As mentioned previously, the variable @code{c-offsets-alist} is an
|
|
|
1229 association list between syntactic symbols and the offsets to be applied
|
|
|
1230 for those symbols. In fact, these offset values can be an integer, a
|
|
|
1231 function or variable name, or one of the following symbols: @code{+},
|
|
|
1232 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. These symbols
|
|
|
1233 describe offset in multiples of the value of the variable
|
|
|
1234 @code{c-basic-offset}. By defining a style's indentation in terms of
|
|
|
1235 this fundamental variable, you can change the amount of whitespace given
|
|
|
1236 to an indentation level while leaving the same relationship between
|
|
|
1237 levels. Here are multiples of @code{c-basic-offset} that the special
|
|
|
1238 symbols correspond to:
|
|
|
1239
|
|
|
1240 @itemize @bullet
|
|
|
1241
|
|
|
1242 @item
|
|
|
1243 @code{+ } = @code{c-basic-offset} times 1
|
|
|
1244 @item
|
|
|
1245 @code{- } = @code{c-basic-offset} times -1
|
|
|
1246 @item
|
|
|
1247 @code{++} = @code{c-basic-offset} times 2
|
|
|
1248 @item
|
|
|
1249 @code{--} = @code{c-basic-offset} times -2
|
|
|
1250 @item
|
|
|
1251 @code{* } = @code{c-basic-offset} times 0.5
|
|
|
1252 @item
|
|
|
1253 @code{/ } = @code{c-basic-offset} times -0.5
|
|
|
1254
|
|
|
1255 @end itemize
|
|
|
1256
|
|
|
1257 @noindent
|
|
|
1258 So, for example, because most of the default offsets are defined in
|
|
|
1259 terms of @code{+}, @code{-}, and @code{0}, if you like the general
|
|
|
1260 indentation style, but you use 4 spaces instead of 2 spaces per level,
|
|
|
1261 you can probably achieve your style just by changing
|
|
|
1262 @code{c-basic-offset} like so (in your @file{.emacs} file)@footnote{The
|
|
|
1263 reason you need to use @code{setq-default} instead of @code{setq} is
|
|
|
1264 that @code{c-basic-offset} is a buffer local variable, as are most of
|
|
|
1265 the @code{cc-mode} configuration variables. If you were to put this
|
|
|
1266 code in, e.g. your @code{c-mode-common-hook} function, you could use
|
|
|
1267 @code{setq}.}:
|
|
|
1268 @example
|
|
|
1269
|
|
|
1270 (setq-default c-basic-offset 4)
|
|
|
1271
|
|
|
1272 @end example
|
|
|
1273
|
|
|
1274 @noindent
|
|
|
1275 This would change
|
|
|
1276 @example
|
|
|
1277 @group
|
|
|
1278
|
|
|
1279 int add( int val, int incr, int doit )
|
|
|
1280 @{
|
|
|
1281 if( doit )
|
|
|
1282 @{
|
|
|
1283 return( val + incr );
|
|
|
1284 @}
|
|
|
1285 return( val );
|
|
|
1286 @}
|
|
|
1287
|
|
|
1288 @end group
|
|
|
1289 @end example
|
|
|
1290
|
|
|
1291 @noindent
|
|
|
1292 to
|
|
|
1293 @example
|
|
|
1294 @group
|
|
|
1295
|
|
|
1296 int add( int val, int incr, int doit )
|
|
|
1297 @{
|
|
|
1298 if( doit )
|
|
|
1299 @{
|
|
|
1300 return( val + incr );
|
|
|
1301 @}
|
|
|
1302 return( val );
|
|
|
1303 @}
|
|
|
1304
|
|
|
1305 @end group
|
|
|
1306 @end example
|
|
|
1307
|
|
|
1308 To change indentation styles more radically, you will want to change the
|
|
|
1309 value associated with the syntactic symbols in the
|
|
|
1310 @code{c-offsets-alist} variable. First, I'll show you how to do that
|
|
|
1311 interactively, then I'll describe how to make changes to your
|
|
|
1312 @file{.emacs} file so that your changes are more permanent.
|
|
|
1313
|
|
|
1314 @menu
|
|
|
1315 * Interactive Customization::
|
|
|
1316 * Permanent Customization::
|
|
|
1317 * Styles::
|
|
|
1318 * Advanced Customizations::
|
|
|
1319 @end menu
|
|
|
1320
|
|
|
1321 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1322 @node Interactive Customization, Permanent Customization, , Customizing Indentation
|
|
|
1323 @comment node-name, next, previous,up
|
|
|
1324
|
|
|
1325 @section Interactive Customization
|
|
|
1326 @cindex Interactive Customization
|
|
|
1327 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1328
|
|
|
1329 As an example of how to customize indentation, let's change the
|
|
|
1330 style of example 2 above from:
|
|
|
1331 @example
|
|
|
1332 @group
|
|
|
1333
|
|
|
1334 1: int add( int val, int incr, int doit )
|
|
|
1335 2: @{
|
|
|
1336 3: if( doit )
|
|
|
1337 4: @{
|
|
|
1338 5: return( val + incr );
|
|
|
1339 6: @}
|
|
|
1340 7: return( val );
|
|
|
1341 8: @}
|
|
|
1342
|
|
|
1343 @end group
|
|
|
1344 @end example
|
|
|
1345 @noindent
|
|
|
1346 to:
|
|
|
1347 @example
|
|
|
1348 @group
|
|
|
1349
|
|
|
1350 1: int add( int val, int incr, int doit )
|
|
|
1351 2: @{
|
|
|
1352 3: if( doit )
|
|
|
1353 4: @{
|
|
|
1354 5: return( val + incr );
|
|
|
1355 6: @}
|
|
|
1356 7: return( val );
|
|
|
1357 8: @}
|
|
|
1358
|
|
|
1359 @end group
|
|
|
1360 @end example
|
|
|
1361
|
|
|
1362 In other words, we want to change the indentation of braces that open a
|
|
|
1363 block following a condition so that the braces line up under the
|
|
|
1364 conditional, instead of being indented. Notice that the construct we
|
|
|
1365 want to change starts on line 4. To change the indentation of a line,
|
|
|
1366 we need to see which syntactic component affect the offset calculations
|
|
|
1367 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
|
|
|
1368 @example
|
|
|
1369
|
|
|
1370 ((substatement-open . 46))
|
|
|
1371
|
|
|
1372 @end example
|
|
|
1373
|
|
|
1374 @findex c-set-offset
|
|
|
1375 @findex set-offset (c-)
|
|
|
1376 @kindex C-c C-o
|
|
|
1377 @noindent
|
|
|
1378 so we know that to change the offset of the open brace, we need to
|
|
|
1379 change the indentation for the @code{substatement-open} syntactic
|
|
|
1380 symbol. To do this interactively, just hit @kbd{C-c C-o}
|
|
|
1381 (@code{c-set-offset}). This prompts you for the syntactic symbol to
|
|
|
1382 change, providing a reasonable default. In this case, the default is
|
|
|
1383 @code{substatement-open}, which is just the syntactic symbol we want to
|
|
|
1384 change!
|
|
|
1385
|
|
|
1386 After you hit return, @code{cc-mode} will then prompt you for the new
|
|
|
1387 offset value, with the old value as the default. The default in this
|
|
|
1388 case is @samp{+}, so hit backspace to delete the @samp{+}, then hit
|
|
|
1389 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
|
|
|
1390 syntactic symbol @code{substatement-open} in the @code{c-offsets-alist}
|
|
|
1391 variable.
|
|
|
1392
|
|
|
1393 @findex c-indent-defun
|
|
|
1394 @findex indent-defun (c-)
|
|
|
1395 @kindex C-c C-q
|
|
|
1396 To check your changes quickly, just hit @kbd{C-c C-q}
|
|
|
1397 (@code{c-indent-defun}) to reindent the entire function. The example
|
|
|
1398 should now look like:
|
|
|
1399 @example
|
|
|
1400 @group
|
|
|
1401
|
|
|
1402 1: int add( int val, int incr, int doit )
|
|
|
1403 2: @{
|
|
|
1404 3: if( doit )
|
|
|
1405 4: @{
|
|
|
1406 5: return( val + incr );
|
|
|
1407 6: @}
|
|
|
1408 7: return( val );
|
|
|
1409 8: @}
|
|
|
1410
|
|
|
1411 @end group
|
|
|
1412 @end example
|
|
|
1413
|
|
|
1414 Notice how just changing the open brace offset on line 4 is all we
|
|
|
1415 needed to do. Since the other affected lines are indented relative to
|
|
|
1416 line 4, they are automatically indented the way you'd expect. For more
|
|
|
1417 complicated examples, this may not always work. The general approach to
|
|
|
1418 take is to always start adjusting offsets for lines higher up in the
|
|
|
1419 file, then re-indent and see if any following lines need further
|
|
|
1420 adjustments.
|
|
|
1421
|
|
|
1422 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1423 @node Permanent Customization, Styles, Interactive Customization, Customizing Indentation
|
|
|
1424 @comment node-name, next, previous,up
|
|
|
1425
|
|
|
1426 @section Permanent Indentation
|
|
|
1427 @cindex Permanent Indentation
|
|
|
1428 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1429
|
|
|
1430 @vindex c-mode-common-hook
|
|
|
1431 @vindex c-mode-hook
|
|
|
1432 @vindex c++-mode-hook
|
|
|
1433 @vindex objc-mode-hook
|
|
|
1434 @vindex java-mode-hook
|
|
|
1435 @cindex hooks
|
|
|
1436 To make this change permanent, you need to add some lisp code to your
|
|
|
1437 @file{.emacs} file. @code{cc-mode} provides four hooks that you can use
|
|
|
1438 to customize your language editing styles. Four language specific hooks
|
|
|
1439 are provided, according to Emacs major mode conventions:
|
|
|
1440 @code{c-mode-hook}, @code{c++-mode-hook}, @code{objc-mode-hook}, and
|
|
|
1441 @code{java-mode-hook}. These get run as the last thing when you enter
|
|
|
1442 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, or
|
|
|
1443 @code{java-mode-hook} respectively. @code{cc-mode} also provides a hook
|
|
|
1444 called @code{c-mode-common-hook} which is run by all three modes
|
|
|
1445 @emph{before} the language specific hook. Thus, to make changes
|
|
|
1446 consistently across all supported @code{cc-mode} modes, use
|
|
|
1447 @code{c-mode-common-hook}. Most of the examples in this section will
|
|
|
1448 assume you are using the common hook.
|
|
|
1449
|
|
|
1450 Here's a simplified example of what you can add to your @file{.emacs}
|
|
|
1451 file to make the changes described in the previous section
|
|
|
1452 (@ref{Interactive Customization}) more permanent. See the Emacs
|
|
|
1453 manuals for more information on customizing Emacs via hooks.
|
|
|
1454 @xref{Sample .emacs File} for a more complete sample @file{.emacs} file.
|
|
|
1455 @footnote{The use of @code{add-hook} in this example only works for
|
|
|
1456 Emacs 19. Workarounds are available if you are using Emacs 18.}
|
|
|
1457 @example
|
|
|
1458 @group
|
|
|
1459
|
|
|
1460 (defun my-c-mode-common-hook ()
|
|
|
1461 ;; my customizations for all of c-mode, c++-mode, objc-mode, java-mode
|
|
|
1462 (c-set-offset 'substatement-open 0)
|
|
|
1463 ;; other customizations can go here
|
|
|
1464 )
|
|
|
1465 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
1466
|
|
|
1467 @end group
|
|
|
1468 @end example
|
|
|
1469
|
|
|
1470 For complex customizations, you will probably want to set up a
|
|
|
1471 @emph{style} that groups all your customizations under a single
|
|
|
1472 name.
|
|
|
1473
|
|
|
1474 The offset value can also be a function, and this is how power users
|
|
|
1475 gain enormous flexibility in customizing indentation. @xref{Advanced
|
|
|
1476 Customizations} for details.
|
|
|
1477
|
|
|
1478 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1479 @node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
|
|
|
1480 @comment node-name, next, previous,up
|
|
|
1481
|
|
|
1482 @section Styles
|
|
|
1483 @cindex Styles
|
|
|
1484 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1485
|
|
|
1486 Most people only need to edit code formatted in just a few well-defined
|
|
|
1487 and consistent styles. For example, their organization might impose a
|
|
|
1488 ``blessed'' style that all its programmers must conform to. Similarly,
|
|
|
1489 people who work on GNU software will have to use the GNU coding style on
|
|
|
1490 C code. Some shops are more lenient, allowing some variety of coding
|
|
|
1491 styles, and as programmers come and go, there could be a number of
|
|
|
1492 styles in use. For this reason, @code{cc-mode} makes it convenient for
|
|
|
1493 you to set up logical groupings of customizations called @dfn{styles},
|
|
|
1494 associate a single name for any particular style, and pretty easily
|
|
|
1495 start editing new or existing code using these styles. This chapter
|
|
|
1496 describes how to set up styles and how to edit your C code using styles.
|
|
|
1497
|
|
|
1498 @menu
|
|
|
1499 * Built-in Styles::
|
|
|
1500 * Adding Styles::
|
|
|
1501 * File Styles::
|
|
|
1502 @end menu
|
|
|
1503
|
|
|
1504
|
|
|
1505 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1506 @node Built-in Styles, Adding Styles, , Styles
|
|
|
1507 @comment node-name, next, previous,up
|
|
|
1508
|
|
|
1509 @subsection Built-in Styles
|
|
|
1510 @cindex Built-in Styles
|
|
|
1511 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1512
|
|
|
1513 If you're lucky, one of @code{cc-mode}'s built-in styles might be just
|
|
|
1514 what you're looking for. Some of the most common C and C++ styles are
|
|
|
1515 already built-in. These include:
|
|
|
1516
|
|
|
1517 @itemize @bullet
|
|
|
1518 @item
|
|
|
1519 @cindex GNU style
|
|
|
1520 @code{gnu} -- coding style blessed by the Free Software Foundation
|
|
|
1521 for C code in GNU programs.
|
|
|
1522
|
|
|
1523 @item
|
|
|
1524 @cindex K&R style
|
|
|
1525 @code{k&r} -- The classic Kernighan and Ritchie style for C code.
|
|
|
1526
|
|
|
1527 @item
|
|
|
1528 @cindex BSD style
|
|
|
1529 @code{bsd} -- @strong{<TBD> Anybody know anything about the history of
|
|
|
1530 this style?}
|
|
|
1531
|
|
|
1532 @item
|
|
|
1533 @cindex Stroustrup style
|
|
|
1534 @code{stroustrup} -- The classic Stroustrup style for C++ code.
|
|
|
1535
|
|
|
1536 @item
|
|
|
1537 @cindex Whitesmith style
|
|
|
1538 @code{whitesmith} -- @strong{<TBD> Anybody know anything about the history of
|
|
|
1539 this style?}
|
|
|
1540
|
|
|
1541 @item
|
|
|
1542 @cindex Ellemtel style
|
|
|
1543 @code{ellemtel} -- Popular C++ coding standards as defined by
|
|
|
1544 ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats
|
|
|
1545 Henricson, Ellemtel @footnote{This document is ftp'able from
|
|
|
1546 @code{euagate.eua.ericsson.se}}.
|
|
|
1547
|
|
|
1548 @item
|
|
|
1549 @cindex Java style
|
|
|
1550 @cindex java-mode
|
|
|
1551 @code{java} -- The style for editing Java code. Note that this style is
|
|
|
1552 automatically installed when you enter @code{java-mode}.
|
|
|
1553
|
|
|
1554 @item
|
|
|
1555 @cindex CC-MODE style
|
|
|
1556 @code{CC-MODE} -- Style that encapsulates the default values of the
|
|
|
1557 @code{cc-mode} variables. See below for details.
|
|
|
1558
|
|
|
1559 @end itemize
|
|
|
1560
|
|
|
1561 @findex c-set-style
|
|
|
1562 @findex set-style (c-)
|
|
|
1563 If you'd like to experiment with these built-in styles you can simply
|
|
|
1564 type the following in a @code{cc-mode} buffer:
|
|
|
1565 @example
|
|
|
1566 @group
|
|
|
1567
|
|
|
1568 @kbd{M-x c-set-style RET @var{STYLE-NAME} RET}
|
|
|
1569
|
|
|
1570 @end group
|
|
|
1571 @end example
|
|
|
1572 @noindent
|
|
|
1573 Note that all style names are case insensitive, even the ones you define.
|
|
|
1574
|
|
|
1575 Setting a style in this way does @emph{not} automatically re-indent your
|
|
|
1576 file. For commands that you can use to view the effect of your changes,
|
|
|
1577 see @ref{Indentation Commands}.
|
|
|
1578
|
|
|
1579 Once you find a built-in style you like, you can make the change
|
|
|
1580 permanent by adding a call to your @file{.emacs} file. Let's say for
|
|
|
1581 example that you want to use the @code{ellemtel} style in all your
|
|
|
1582 files. You would add this:
|
|
|
1583 @example
|
|
|
1584 @group
|
|
|
1585
|
|
|
1586 (defun my-c-mode-common-hook ()
|
|
|
1587 ;; use Ellemtel style for all C, C++, and Objective-C code
|
|
|
1588 (c-set-style "ellemtel")
|
|
|
1589 ;; other customizations can go here
|
|
|
1590 )
|
|
|
1591 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
1592
|
|
|
1593 @end group
|
|
|
1594 @end example
|
|
|
1595
|
|
|
1596 There is one other special style you can use, called @code{CC-MODE}.
|
|
|
1597 This is a style that is calculated by @code{cc-mode} when it starts up.
|
|
|
1598 The @code{CC-MODE} style is also special because all other styles
|
|
|
1599 implicitly inherit from it; in other words, whenever you set a style,
|
|
|
1600 @code{cc-mode} first re-instates the @code{CC-MODE} style, then applies
|
|
|
1601 your new style configurations.
|
|
|
1602
|
|
|
1603 The @code{CC-MODE} style exists because once @code{cc-mode} initializes,
|
|
|
1604 it institutes the @code{gnu} style for compatibility with BOCM's
|
|
|
1605 defaults. Any customizations you make in mode hooks will be based on
|
|
|
1606 the @code{gnu} style, unless you first do a @code{c-set-style} to
|
|
|
1607 @code{CC-MODE} or some other built-in style.
|
|
|
1608
|
|
|
1609
|
|
|
1610 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1611 @node Adding Styles, File Styles, Built-in Styles, Styles
|
|
|
1612 @comment node-name, next, previous,up
|
|
|
1613
|
|
|
1614 @subsection Adding Styles
|
|
|
1615 @cindex Adding Styles
|
|
|
1616 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1617
|
|
|
1618 @vindex c-style-alist
|
|
|
1619 @vindex style-alist (c-)
|
|
|
1620 @findex c-add-style
|
|
|
1621 @findex add-style (c-)
|
|
|
1622 If none of the built-in styles is appropriate, you'll probably want to
|
|
|
1623 add a new style definition. Styles are kept in the @code{c-style-alist}
|
|
|
1624 variable, but you probably won't want to modify this variable directly.
|
|
|
1625 @code{cc-mode} provides a function, called @code{c-add-style}, that you
|
|
|
1626 can use to easily add new styles or update existing styles. This
|
|
|
1627 function takes two arguments, a @var{stylename} string, and an
|
|
|
1628 association list @var{description} of style customizations. If
|
|
|
1629 @var{stylename} is not already in @code{c-style-alist}, the new style is
|
|
|
1630 added, otherwise the style already associated with @var{stylename} is
|
|
|
1631 changed to the new @var{description}. This function also takes an
|
|
|
1632 optional third argument, which if non-@code{nil}, automatically
|
|
|
1633 institutes the new style in the current buffer.
|
|
|
1634
|
|
|
1635 The sample @file{.emacs} file provides a concrete example of how a new
|
|
|
1636 style can be added and automatically set. @xref{Sample .emacs File}.
|
|
|
1637
|
|
|
1638 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1639 @node File Styles, , Adding Styles, Styles
|
|
|
1640 @comment node-name, next, previous,up
|
|
|
1641
|
|
|
1642 @subsection File Styles
|
|
|
1643 @cindex File Styles
|
|
|
1644 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1645
|
|
|
1646 @cindex local variables
|
|
|
1647 The Emacs manual describes how you can customize certain variables on a
|
|
|
1648 per-file basis by including a @dfn{Local Variable} block at the end of
|
|
|
1649 the file. So far, you've only seen a functional interface to
|
|
|
1650 @code{cc-mode}, which is highly inconvenient for use in a Local Variable
|
|
|
1651 block. @code{cc-mode} provides two variables that make it easier for
|
|
|
1652 you to customize your style on a per-file basis.
|
|
|
1653
|
|
|
1654 @vindex c-file-style
|
|
|
1655 @vindex file-style (c-)
|
|
|
1656 @vindex c-file-offsets
|
|
|
1657 @vindex file-offsets (c-)
|
|
|
1658
|
|
|
1659 The variable @code{c-file-style} can be set to a style name string as
|
|
|
1660 described in @ref{Built-in Styles}. When the file is visited,
|
|
|
1661 @code{cc-mode} will automatically set the file's style to this style
|
|
|
1662 using @code{c-set-style}.
|
|
|
1663
|
|
|
1664 @vindex c-offsets-alist
|
|
|
1665 @vindex offsets-alist (c-)
|
|
|
1666 @findex c-set-offset
|
|
|
1667 @findex set-offset (c-)
|
|
|
1668 Another variable, @code{c-file-offsets}, takes an association list
|
|
|
1669 similar to what is allowed in @code{c-offsets-alist}. When the file is
|
|
|
1670 visited, @code{cc-mode} will automatically institute these offets using
|
|
|
1671 @code{c-set-offset}.
|
|
|
1672
|
|
|
1673 Note that file style settings (i.e. @code{c-file-style}) are applied
|
|
|
1674 before file offset settings (i.e. @code{c-file-offsets}).
|
|
|
1675
|
|
|
1676
|
|
|
1677 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1678 @node Advanced Customizations, , Styles, Customizing Indentation
|
|
|
1679 @comment node-name, next, previous,up
|
|
|
1680
|
|
|
1681 @section Advanced Customizations
|
|
|
1682 @cindex Advanced Customizations
|
|
|
1683 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1684
|
|
|
1685 @vindex c-style-alist
|
|
|
1686 @vindex style-alist (c-)
|
|
|
1687 @vindex c-basic-offset
|
|
|
1688 @vindex basic-offset (c-)
|
|
|
1689 For most users, @code{cc-mode} will support their coding styles with
|
|
|
1690 very little need for customizations. Usually, one of the standard
|
|
|
1691 styles defined in @code{c-style-alist} will do the trick. At most,
|
|
|
1692 perhaps one of the syntactic symbol offsets will need to be tweaked
|
|
|
1693 slightly, or maybe @code{c-basic-offset} will need to be changed.
|
|
|
1694 However, some styles require a more advanced ability for customization,
|
|
|
1695 and one of the real strengths of @code{cc-mode} is that the syntactic
|
|
|
1696 analysis model provides a very flexible framework for customizing
|
|
|
1697 indentation. This allows you to perform special indentation calculations
|
|
|
1698 for situations not handled by the mode directly.
|
|
|
1699
|
|
|
1700 @menu
|
|
|
1701 * Custom Indentation Functions::
|
|
|
1702 * Custom Brace and Colon Hanging::
|
|
|
1703 * Customizing Semi-colons and Commas::
|
|
|
1704 * Other Special Indentations::
|
|
|
1705 @end menu
|
|
|
1706
|
|
|
1707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1708 @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
|
|
|
1709 @comment node-name, next, previous,up
|
|
|
1710
|
|
|
1711 @subsection Custom Indentation Functions
|
|
|
1712 @cindex Custom Indentation Functions
|
|
|
1713 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1714
|
|
|
1715 @cindex custom indentation functions
|
|
|
1716 One of the most common ways to customize @code{cc-mode} is by writing
|
|
|
1717 @dfn{custom indentation functions} and associating them with specific
|
|
|
1718 syntactic symbols (see @ref{Syntactic Symbols}). @code{cc-mode} itself
|
|
|
1719 uses custom indentation functions to provide more sophisticated
|
|
|
1720 indentation, for example when lining up C++ stream operator blocks:
|
|
|
1721 @example
|
|
|
1722 @group
|
|
|
1723
|
|
|
1724 1: void main(int argc, char**)
|
|
|
1725 2: @{
|
|
|
1726 3: cout << "There were "
|
|
|
1727 4: << argc
|
|
|
1728 5: << "arguments passed to the program"
|
|
|
1729 6: << endl;
|
|
|
1730 7: @}
|
|
|
1731
|
|
|
1732 @end group
|
|
|
1733 @end example
|
|
|
1734
|
|
|
1735 In this example, lines 4 through 6 are assigned the @code{stream-op}
|
|
|
1736 syntactic symbol. If @code{stream-op} had an offset of @code{+}, and
|
|
|
1737 @code{c-basic-offset} was 2, lines 4 through 6 would simply be indented
|
|
|
1738 two spaces to the right of line 3. But perhaps we'd like @code{cc-mode}
|
|
|
1739 to be a little more intelligent so that it offsets the stream operators
|
|
|
1740 under the operator in line 3. To do this, we have to write a custom
|
|
|
1741 indentation function which finds the column of first stream operator on
|
|
|
1742 the first line of the statement. Here is the lisp code (from the
|
|
|
1743 @file{cc-mode.el} source file) that implements this:
|
|
|
1744 @example
|
|
|
1745 @group
|
|
|
1746
|
|
|
1747 (defun c-lineup-streamop (langelem)
|
|
|
1748 ;; lineup stream operators
|
|
|
1749 (save-excursion
|
|
|
1750 (let* ((relpos (cdr langelem))
|
|
|
1751 (curcol (progn (goto-char relpos)
|
|
|
1752 (current-column))))
|
|
|
1753 (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
|
|
|
1754 (goto-char (match-beginning 0))
|
|
|
1755 (- (current-column) curcol))))
|
|
|
1756
|
|
|
1757 @end group
|
|
|
1758 @end example
|
|
|
1759 @noindent
|
|
|
1760 Custom indent functions take a single argument, which is a syntactic
|
|
|
1761 component cons cell (see @ref{Syntactic Analysis}). The
|
|
|
1762 function returns an integer offset value that will be added to the
|
|
|
1763 running total indentation for the lne. Note that what actually gets
|
|
|
1764 returned is the difference between the column that the first stream
|
|
|
1765 operator is on, and the column of the buffer relative position passed in
|
|
|
1766 the function's argument. Remember that @code{cc-mode} automatically
|
|
|
1767 adds in the column of the component's relative buffer position and we
|
|
|
1768 don't want that value added into the final total twice.
|
|
|
1769
|
|
|
1770 @cindex stream-op syntactic symbol
|
|
|
1771 @findex c-lineup-streamop
|
|
|
1772 @findex lineup-streamop (c-)
|
|
|
1773 Now, to associate the function @code{c-lineup-streamop} with the
|
|
|
1774 @code{stream-op} syntactic symbol, we can add something like the
|
|
|
1775 following to our @code{c++-mode-hook}@footnote{It probably makes more
|
|
|
1776 sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
|
|
|
1777 since stream operators are only relevent for C++.}:
|
|
|
1778 @example
|
|
|
1779
|
|
|
1780 (c-set-offset 'stream-op 'c-lineup-streamop)
|
|
|
1781
|
|
|
1782 @end example
|
|
|
1783
|
|
|
1784 @kindex C-c C-q
|
|
|
1785 Now the function looks like this after re-indenting (using @kbd{C-c
|
|
|
1786 C-q}):
|
|
|
1787 @example
|
|
|
1788 @group
|
|
|
1789
|
|
|
1790 1: void main(int argc, char**)
|
|
|
1791 2: @{
|
|
|
1792 3: cout << "There were "
|
|
|
1793 4: << argc
|
|
|
1794 5: << "arguments passed to the program"
|
|
|
1795 6: << endl;
|
|
|
1796 7: @}
|
|
|
1797
|
|
|
1798 @end group
|
|
|
1799 @end example
|
|
|
1800
|
|
|
1801 @vindex c-offsets-alist
|
|
|
1802 @vindex offsets-alist (c-)
|
|
|
1803 Custom indentation functions can be as simple or as complex as you like,
|
|
|
1804 and any syntactic symbol that appears in @code{c-offsets-alist} can have
|
|
|
1805 a custom indentation function associated with it.
|
|
|
1806
|
|
|
1807 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1808 @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
|
|
|
1809 @comment node-name, next, previous,up
|
|
|
1810
|
|
|
1811 @subsection Custom Brace and Colon Hanging
|
|
|
1812 @cindex Custom Brace and Colon Hanging
|
|
|
1813 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1814
|
|
|
1815 @vindex c-hanging-braces-alist
|
|
|
1816 @vindex hanging-braces-alist (c-)
|
|
|
1817 Syntactic symbols aren't the only place where you can customize
|
|
|
1818 @code{cc-mode} with the lisp equivalent of callback functions. Brace
|
|
|
1819 hanginess can also be determined by custom functions associated with
|
|
|
1820 syntactic symbols on the @code{c-hanging-braces-alist} variable.
|
|
|
1821 Remember that @var{ACTION}'s are typically a list containing some
|
|
|
1822 combination of the symbols @code{before} and @code{after} (see
|
|
|
1823 @ref{Hanging Braces}). However, an @var{ACTION} can also be a function
|
|
|
1824 symbol which gets called when a brace matching that syntactic symbol is
|
|
|
1825 typed.
|
|
|
1826
|
|
|
1827 @cindex customizing brace hanging
|
|
|
1828 These @var{ACTION} functions are called with two arguments: the
|
|
|
1829 syntactic symbol for the brace, and the buffer position at which the
|
|
|
1830 brace was inserted. The @var{ACTION} function is expected to return a
|
|
|
1831 list containing some combination of @code{before} and @code{after}. The
|
|
|
1832 function can also return @code{nil}. This return value has the normal
|
|
|
1833 brace hanging semantics described in @ref{Hanging Braces}.
|
|
|
1834
|
|
|
1835 As an example, @code{cc-mode} itself uses this feature to dynamically
|
|
|
1836 determine the hanginess of braces which close @samp{do-while}
|
|
|
1837 constructs:
|
|
|
1838 @example
|
|
|
1839 @group
|
|
|
1840
|
|
|
1841 void do_list( int count, char** atleast_one_string )
|
|
|
1842 @{
|
|
|
1843 int i=0;
|
|
|
1844 do @{
|
|
|
1845 handle_string( atleast_one_string( i ));
|
|
|
1846 i++;
|
|
|
1847 @} while( i < count );
|
|
|
1848 @}
|
|
|
1849
|
|
|
1850 @end group
|
|
|
1851 @end example
|
|
|
1852
|
|
|
1853 @findex c-snug-do-while
|
|
|
1854 @findex snug-do-while (c-)
|
|
|
1855 @code{cc-mode} assigns the @code{block-close} syntactic symbol to the
|
|
|
1856 brace that closes the @code{do} construct, and normally we'd like the
|
|
|
1857 line that follows a @code{block-close} brace to begin on a separate
|
|
|
1858 line. However, with @samp{do-while} constructs, we want the
|
|
|
1859 @code{while} clause to follow the closing brace. To do this, we
|
|
|
1860 associate the @code{block-close} symbol with the @var{ACTION} function
|
|
|
1861 @code{c-snug-do-while}:
|
|
|
1862 @example
|
|
|
1863
|
|
|
1864 (defun c-snug-do-while (syntax pos)
|
|
|
1865 "Dynamically calculate brace hanginess for do-while statements.
|
|
|
1866 Using this function, `while' clauses that end a `do-while' block will
|
|
|
1867 remain on the same line as the brace that closes that block.
|
|
|
1868
|
|
|
1869 See `c-hanging-braces-alist' for how to utilize this function as an
|
|
|
1870 ACTION associated with `block-close' syntax."
|
|
|
1871 (save-excursion
|
|
|
1872 (let (langelem)
|
|
|
1873 (if (and (eq syntax 'block-close)
|
|
|
1874 (setq langelem (assq 'block-close c-syntactic-context))
|
|
|
1875 (progn (goto-char (cdr langelem))
|
|
|
1876 (if (= (following-char) ?@{)
|
|
|
1877 (forward-sexp -1))
|
|
|
1878 (looking-at "\\<do\\>[^_]")))
|
|
|
1879 '(before)
|
|
|
1880 '(before after)))))
|
|
|
1881
|
|
|
1882 @end example
|
|
|
1883
|
|
|
1884 This function simply looks to see if the brace closes a @samp{do-while}
|
|
|
1885 clause and if so, returns the list @samp{@code{(before)}} indicating
|
|
|
1886 that a newline should be inserted before the brace, but not after it.
|
|
|
1887 In all other cases, it returns the list @samp{@code{(before after)}} so
|
|
|
1888 that the brace appears on a line by itself.
|
|
|
1889
|
|
|
1890 @vindex c-syntactic-context
|
|
|
1891 @vindex syntactic-context (c-)
|
|
|
1892 During the call to the brace hanging @var{ACTION} function, the variable
|
|
|
1893 @code{c-syntactic-context} is bound to the full syntactic analysis list.
|
|
|
1894
|
|
|
1895 @cindex customizing colon hanging
|
|
|
1896 @vindex c-hanging-colon-alist
|
|
|
1897 @vindex hanging-colon-alist (c-)
|
|
|
1898 Note that for symmetry, colon hanginess should be customizable by
|
|
|
1899 allowing function symbols as @var{ACTION}s on the
|
|
|
1900 @code{c-hanging-colon-alist} variable. Since no use has actually been
|
|
|
1901 found for this feature, it isn't currently implemented.
|
|
|
1902
|
|
|
1903 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1904 @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
|
|
|
1905 @comment node-name, next, previous,up
|
|
|
1906
|
|
|
1907 @subsection Customizing Semi-colons and Commas
|
|
|
1908 @cindex Customizing Semi-colons and Commas
|
|
|
1909 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1910
|
|
|
1911 @cindex customizing semi-colons and commas
|
|
|
1912 @vindex c-hanging-semi&comma-criteria
|
|
|
1913 @vindex hanging-semi&comma-criteria (c-)
|
|
|
1914 You can also customize the insertion of newlines after semi-colons and
|
|
|
1915 commas, when the auto-newline minor mode is enabled (see @ref{Minor
|
|
|
1916 Modes}). This is controlled by the variable
|
|
|
1917 @code{c-hanging-semi&comma-criteria}, which contains a list of functions
|
|
|
1918 that are called in the order they appear. Each function is called with
|
|
|
1919 zero arguments, and is expected to return one of the following values:
|
|
|
1920
|
|
|
1921 @itemize @bullet
|
|
|
1922 @item
|
|
|
1923 non-@code{nil} -- A newline is inserted, and no more functions from the
|
|
|
1924 list are called.
|
|
|
1925
|
|
|
1926 @item
|
|
|
1927 @code{stop} -- No more functions from the list are called, but no
|
|
|
1928 newline is inserted.
|
|
|
1929
|
|
|
1930 @item
|
|
|
1931 @code{nil} -- No determination is made, and the next function in the
|
|
|
1932 list is called.
|
|
|
1933
|
|
|
1934 @end itemize
|
|
|
1935
|
|
|
1936 If every function in the list is called without a determination being
|
|
|
1937 made, then no newline is added. The default value for this variable is a
|
|
|
1938 list containing a single function which inserts newlines only after
|
|
|
1939 semi-colons which do not appear inside parenthesis lists (i.e. those
|
|
|
1940 that separate @code{for}-clause statements).
|
|
|
1941
|
|
|
1942 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1943 @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
|
|
|
1944 @comment node-name, next, previous,up
|
|
|
1945
|
|
|
1946 @subsection Other Special Indentations
|
|
|
1947 @cindex Customizing Semi-colons and Commas
|
|
|
1948 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1949
|
|
|
1950 @vindex c-special-indent-hook
|
|
|
1951 @vindex special-indent-hook (c-)
|
|
|
1952 One other customization variable is available in @code{cc-mode}:
|
|
|
1953 @code{c-special-indent-hook}. This is a standard hook variable that is
|
|
|
1954 called after every line is indented by @code{cc-mode}. You can use it
|
|
|
1955 to do any special indentation or line adjustments your style dictates,
|
|
|
1956 such as adding extra indentation to constructors or destructor
|
|
|
1957 declarations in a class definition, etc. Note however, that you should
|
|
|
1958 not change point or mark inside your @code{c-special-indent-hook}
|
|
|
1959 functions (i.e. you'll probably want to wrap your function in a
|
|
|
1960 @code{save-excursion}).
|
|
|
1961
|
|
|
1962
|
|
|
1963 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1964 @node Syntactic Symbols, Performance Issues, Customizing Indentation, Top
|
|
|
1965 @comment node-name, next, previous,up
|
|
|
1966
|
|
|
1967 @chapter Syntactic Symbols
|
|
|
1968 @cindex Syntactic Symbols
|
|
|
1969 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
1970
|
|
|
1971 @vindex c-offsets-alist
|
|
|
1972 @vindex offsets-alist (c-)
|
|
|
1973 The complete list of recognized syntactic symbols is described in the
|
|
|
1974 @code{c-offsets-alist} variable. This chapter will provide some
|
|
|
1975 examples to help clarify these symbols.
|
|
|
1976
|
|
|
1977 @cindex -open syntactic symbols
|
|
|
1978 @cindex -close syntactic symbols
|
|
|
1979 Most syntactic symbol names follow a general naming convention. When a
|
|
|
1980 line begins with an open or close brace, the syntactic symbol will
|
|
|
1981 contain the suffix @code{-open} or @code{-close} respectively.
|
|
|
1982
|
|
|
1983 @cindex -intro syntactic symbols
|
|
|
1984 @cindex -cont syntactic symbols
|
|
|
1985 @cindex -block-intro syntactic symbols
|
|
|
1986 Usually, a distinction is made between the first line that introduces a
|
|
|
1987 construct and lines that continue a construct, and the syntactic symbols
|
|
|
1988 that represent these lines will contain the suffix @code{-intro} or
|
|
|
1989 @code{-cont} respectively. As a sub-classification of this scheme, a
|
|
|
1990 line which is the first of a particular brace block construct will
|
|
|
1991 contain the suffix @code{-block-intro}.
|
|
|
1992
|
|
|
1993 @kindex C-c C-s
|
|
|
1994 Let's look at some examples to understand how this works. Remember that
|
|
|
1995 you can check the syntax of any line by using @kbd{C-c C-s}.
|
|
|
1996 @example
|
|
|
1997 @group
|
|
|
1998
|
|
|
1999 1: void
|
|
|
2000 2: swap( int& a, int& b )
|
|
|
2001 3: @{
|
|
|
2002 4: int tmp = a;
|
|
|
2003 5: a = b;
|
|
|
2004 6: b = tmp;
|
|
|
2005 7: int ignored =
|
|
|
2006 8: a + b;
|
|
|
2007 9: @}
|
|
|
2008
|
|
|
2009 @end group
|
|
|
2010 @end example
|
|
|
2011
|
|
|
2012 Line 1 shows a @code{topmost-intro} since it is the first line that
|
|
|
2013 introduces a top-level construct. Line 2 is a continuation of the
|
|
|
2014 top-level construct introduction so it has the syntax
|
|
|
2015 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
|
|
|
2016 the brace that opens a top-level function definition. Line 9 is a
|
|
|
2017 @code{defun-close} since it contains the brace that closes the top-level
|
|
|
2018 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
|
|
|
2019 the first line of a brace-block, which happens to be enclosed in a
|
|
|
2020 top-level function definition.
|
|
|
2021
|
|
|
2022 Lines 5, 6, and 7 are all given @code{statement} syntax since there
|
|
|
2023 isn't much special about them. Note however that line 8 is given
|
|
|
2024 @code{statement-cont} syntax since it continues the statement begun
|
|
|
2025 on the previous line.
|
|
|
2026
|
|
|
2027 Here's another example, which illustrates some C++ class syntactic
|
|
|
2028 symbols:
|
|
|
2029 @example
|
|
|
2030 @group
|
|
|
2031
|
|
|
2032 1: class Bass
|
|
|
2033 2: : public Guitar,
|
|
|
2034 3: public Amplifiable
|
|
|
2035 4: @{
|
|
|
2036 5: public:
|
|
|
2037 6: Bass()
|
|
|
2038 7: : eString( new BassString( 0.105 )),
|
|
|
2039 8: aString( new BassString( 0.085 )),
|
|
|
2040 9: dString( new BassString( 0.065 )),
|
|
|
2041 10: gString( new BassString( 0.045 ))
|
|
|
2042 11: @{
|
|
|
2043 12: eString.tune( 'E' );
|
|
|
2044 13: aString.tune( 'A' );
|
|
|
2045 14: dString.tune( 'D' );
|
|
|
2046 15: gString.tune( 'G' );
|
|
|
2047 16: @}
|
|
|
2048 17: @}
|
|
|
2049
|
|
|
2050 @end group
|
|
|
2051 @end example
|
|
|
2052
|
|
|
2053 As in the previous example, line 1 has the @code{topmost-intro} syntax.
|
|
|
2054 Here however, the brace that opens a C++ class definition on line 4 is
|
|
|
2055 assigned the @code{class-open} syntax. Note that in C++, structs and
|
|
|
2056 unions are essentially equivalent syntactically (and are very similar
|
|
|
2057 semantically), so replacing the @code{class} keyword in the example
|
|
|
2058 above with @code{struct} or @code{union} would still result in a syntax
|
|
|
2059 of @code{class-open} for line 4 @footnote{This is the case even for C
|
|
|
2060 and Objective-C. For consistency, structs in all three languages are
|
|
|
2061 syntactically equivalent to classes. Note however that the keyword
|
|
|
2062 @code{class} is meaningless in C and Objective-C.}. Similarly, line 17
|
|
|
2063 is assigned @code{class-close} syntax.
|
|
|
2064
|
|
|
2065 Line 2 introduces the inheritance list for the class so it is assigned
|
|
|
2066 the @code{inher-intro} syntax, and line 3, which continues the
|
|
|
2067 inheritance list is given @code{inher-cont} syntax.
|
|
|
2068
|
|
|
2069 Things get interesting at line 5. The primary syntactic symbol for this
|
|
|
2070 line is @code{access-label} since this a label keyword that specifies
|
|
|
2071 access protection in C++. However, this line actually shows two
|
|
|
2072 syntactic symbols when you hit @kbd{C-c C-s}. This is because it is
|
|
|
2073 also a top-level construct inside a class definition. Thus the other
|
|
|
2074 syntactic symbol assigned to this line is @code{inclass}. Similarly,
|
|
|
2075 line 6 is given both @code{inclass} and @code{topmost-intro} syntax.
|
|
|
2076
|
|
|
2077 Line 7 introduces a C++ member initialization list and as such is given
|
|
|
2078 @code{member-init-intro} syntax. Note that in this case it is
|
|
|
2079 @emph{not} assigned @code{inclass} since this is not considered a
|
|
|
2080 top-level construct. Lines 8 through 10 are all assigned
|
|
|
2081 @code{member-init-cont} since they continue the member initialization
|
|
|
2082 list started on line 7.
|
|
|
2083
|
|
|
2084 @cindex in-class inline methods
|
|
|
2085 Line 11 is assigned @code{inline-open} because it opens an
|
|
|
2086 @dfn{in-class} C++ inline method definition. This is distinct from, but
|
|
|
2087 related to, the C++ notion of an inline function in that its definition
|
|
|
2088 occurs inside an enclosing class definition, which in C++ implies that
|
|
|
2089 the function should be inlined. For example, if the definition of the
|
|
|
2090 @code{Bass} constructor appeared outside the class definition, line 11
|
|
|
2091 would be given the @code{defun-open} syntax, even if the keyword
|
|
|
2092 @code{inline} appeared before the method name, as in:
|
|
|
2093 @example
|
|
|
2094 @group
|
|
|
2095
|
|
|
2096 class Bass
|
|
|
2097 : public Guitar,
|
|
|
2098 public Amplifiable
|
|
|
2099 @{
|
|
|
2100 public:
|
|
|
2101 Bass();
|
|
|
2102 @}
|
|
|
2103
|
|
|
2104 inline
|
|
|
2105 Bass::Bass()
|
|
|
2106 : eString( new BassString( 0.105 )),
|
|
|
2107 aString( new BassString( 0.085 )),
|
|
|
2108 dString( new BassString( 0.065 )),
|
|
|
2109 gString( new BassString( 0.045 ))
|
|
|
2110 @{
|
|
|
2111 eString.tune( 'E' );
|
|
|
2112 aString.tune( 'A' );
|
|
|
2113 dString.tune( 'D' );
|
|
|
2114 gString.tune( 'G' );
|
|
|
2115 @}
|
|
|
2116
|
|
|
2117 @end group
|
|
|
2118 @end example
|
|
|
2119
|
|
|
2120 @noindent
|
|
|
2121 Similarly, line 16 is given @code{inline-close} syntax.
|
|
|
2122
|
|
|
2123 As in the first example above, line 12 is given @code{defun-block-open}
|
|
|
2124 syntax and lines 13 through 15 are all given @code{statement} syntax.
|
|
|
2125
|
|
|
2126 Here is another (totally contrived) example which illustrates how syntax
|
|
|
2127 is assigned to various conditional constructs:
|
|
|
2128 @example
|
|
|
2129 @group
|
|
|
2130
|
|
|
2131 1: void spam( int index )
|
|
|
2132 2: @{
|
|
|
2133 3: for( int i=0; i<index; i++ )
|
|
|
2134 4: @{
|
|
|
2135 5: if( i == 10 )
|
|
|
2136 6: @{
|
|
|
2137 7: do_something_special();
|
|
|
2138 8: @}
|
|
|
2139 9: else
|
|
|
2140 10: do_something( i );
|
|
|
2141 11: @}
|
|
|
2142 12: do @{
|
|
|
2143 13: another_thing( i-- );
|
|
|
2144 14: @}
|
|
|
2145 15: while( i > 0 );
|
|
|
2146 16: @}
|
|
|
2147
|
|
|
2148
|
|
|
2149 @end group
|
|
|
2150 @end example
|
|
|
2151
|
|
|
2152 @noindent
|
|
|
2153 Only the lines that illustrate new syntactic symbols will be discussed.
|
|
|
2154
|
|
|
2155 Line 4 has a brace which opens a conditional's substatement block. It
|
|
|
2156 is thus assigned @code{substatement-open} syntax, and since line 5 is
|
|
|
2157 the first line in the substatement block, it is assigned
|
|
|
2158 @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned
|
|
|
2159 similar syntax. Line 8 contains the brace that closes the inner
|
|
|
2160 substatement block. It is given the generic syntax @code{block-close},
|
|
|
2161 as are lines 11 and 14.
|
|
|
2162
|
|
|
2163 Line 9 is a little different -- since it contains the keyword
|
|
|
2164 @code{else} matching the @code{if} statement introduced on line 5; it is
|
|
|
2165 given the @code{else-clause} syntax. Note also that line 10 is slightly
|
|
|
2166 different too. Because @code{else} is considered a conditional
|
|
|
2167 introducing keyword @footnote{The list of conditional keywords are (in
|
|
|
2168 C, Objective-C and C++): @code{for}, @code{if}, @code{do}, @code{else},
|
|
|
2169 @code{while}, and @code{switch}. C++ has two additional conditional
|
|
|
2170 keywords: @code{try} and @code{catch}.}, and because the following
|
|
|
2171 substatement is not a brace block, line 10 is assigned the
|
|
|
2172 @code{substatement} syntax.
|
|
|
2173
|
|
|
2174 One other difference is seen on line 15. The @code{while} construct
|
|
|
2175 that closes a @code{do} conditional is given the special syntax
|
|
|
2176 @code{do-while-closure} if it appears on a line by itself. Note that if
|
|
|
2177 the @code{while} appeared on the same line as the preceding close brace,
|
|
|
2178 that line would have been assigned @code{block-close} syntax instead.
|
|
|
2179
|
|
|
2180 Switch statements have their own set of syntactic symbols. Here's an
|
|
|
2181 example:
|
|
|
2182 @example
|
|
|
2183 @group
|
|
|
2184
|
|
|
2185 1: void spam( enum Ingredient i )
|
|
|
2186 2: @{
|
|
|
2187 3: switch( i ) @{
|
|
|
2188 4: case Ham:
|
|
|
2189 5: be_a_pig();
|
|
|
2190 6: break;
|
|
|
2191 7: case Salt:
|
|
|
2192 8: drink_some_water();
|
|
|
2193 9: break;
|
|
|
2194 10: default:
|
|
|
2195 11: @{
|
|
|
2196 12: what_is_it();
|
|
|
2197 13: break;
|
|
|
2198 14: @}
|
|
|
2199 15: @}
|
|
|
2200 14: @}
|
|
|
2201
|
|
|
2202 @end group
|
|
|
2203 @end example
|
|
|
2204
|
|
|
2205 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
|
|
|
2206 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
|
|
|
2207 is treated slightly differently since it contains a brace that opens a
|
|
|
2208 block -- it is given @code{statement-case-open} syntax.
|
|
|
2209
|
|
|
2210 @cindex brace lists
|
|
|
2211 There are a set of syntactic symbols that are used to recognize
|
|
|
2212 constructs inside of brace lists. A brace list is defined as an
|
|
|
2213 @code{enum} or aggregate initializer list, such as might statically
|
|
|
2214 initialize an array of structs. For example:
|
|
|
2215 @example
|
|
|
2216 @group
|
|
|
2217
|
|
|
2218 1: static char* ingredients[] =
|
|
|
2219 2: @{
|
|
|
2220 3: "Ham",
|
|
|
2221 4: "Salt",
|
|
|
2222 5: NULL
|
|
|
2223 6: @}
|
|
|
2224
|
|
|
2225 @end group
|
|
|
2226 @end example
|
|
|
2227
|
|
|
2228 Following convention, line 2 in this example is assigned
|
|
|
2229 @code{brace-list-open} syntax, and line 3 is assigned
|
|
|
2230 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
|
|
|
2231 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
|
|
|
2232 @code{brace-list-entry} syntax, as would all subsequent lines in this
|
|
|
2233 initializer list.
|
|
|
2234
|
|
|
2235 A number of syntactic symbols are associated with parenthesis lists,
|
|
|
2236 a.k.a argument lists, as found in function declarations and function
|
|
|
2237 calls. This example illustrates these:
|
|
|
2238 @example
|
|
|
2239 @group
|
|
|
2240
|
|
|
2241 1: void a_function( int line1,
|
|
|
2242 2: int line2 );
|
|
|
2243 3:
|
|
|
2244 4: void a_longer_function(
|
|
|
2245 5: int line1,
|
|
|
2246 6: int line2
|
|
|
2247 7: );
|
|
|
2248 8:
|
|
|
2249 9: void call_them( int line1, int line2 )
|
|
|
2250 10: @{
|
|
|
2251 11: a_function(
|
|
|
2252 12: line1,
|
|
|
2253 13: line2
|
|
|
2254 14: );
|
|
|
2255 15:
|
|
|
2256 16: a_longer_function( line1,
|
|
|
2257 17: line2 );
|
|
|
2258 18: @}
|
|
|
2259
|
|
|
2260 @end group
|
|
|
2261 @end example
|
|
|
2262
|
|
|
2263 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
|
|
|
2264 the first line following the open parenthesis, and lines 7 and 14 are
|
|
|
2265 assigned @code{arglist-close} syntax since they contain the parenthesis
|
|
|
2266 that closes the argument list.
|
|
|
2267
|
|
|
2268 The other lines with relevant syntactic symbols include lines 2 and 17
|
|
|
2269 which are assigned @code{arglist-cont-nonempty} syntax. What this means
|
|
|
2270 is that they continue an argument list, but that the line containing the
|
|
|
2271 parenthesis that opens the list is @emph{non-empty} following the open
|
|
|
2272 parenthesis. Contrast this against lines 6 and 13 which are assigned
|
|
|
2273 @code{arglist-cont} syntax. This is because the parenthesis that opens
|
|
|
2274 their argument lists is the last character on that line @footnote{The
|
|
|
2275 need for this somewhat confusing arrangement is that the typical
|
|
|
2276 indentation desired for these lines is calculated very differently.
|
|
|
2277 This should be simplified in version 5 of @code{cc-mode}, along with the
|
|
|
2278 added distinction between argument lists in function declarations, and
|
|
|
2279 argument lists in function calls.}.
|
|
|
2280
|
|
|
2281 Note that there is no @code{arglist-open} syntax. This is because any
|
|
|
2282 parenthesis that opens an argument list, appearing on a separate line,
|
|
|
2283 is assigned the @code{statement-cont} syntax instead.
|
|
|
2284
|
|
|
2285 A few miscellaneous syntactic symbols that haven't been previously
|
|
|
2286 covered are illustrated by this example:
|
|
|
2287 @example
|
|
|
2288 @group
|
|
|
2289
|
|
|
2290 1: void Bass::play( int volume )
|
|
|
2291 2: const
|
|
|
2292 3: @{
|
|
|
2293 4: /* this line starts a multi-line
|
|
|
2294 5: * comment. This line should get `c' syntax */
|
|
|
2295 6:
|
|
|
2296 7: char* a_long_multiline_string = "This line starts a multi-line \
|
|
|
2297 8: string. This line should get `string' syntax.";
|
|
|
2298 9:
|
|
|
2299 10: note:
|
|
|
2300 11: @{
|
|
|
2301 12: #ifdef LOCK
|
|
|
2302 13: Lock acquire();
|
|
|
2303 14: #endif // LOCK
|
|
|
2304 15: slap_pop();
|
|
|
2305 16: cout << "I played "
|
|
|
2306 17: << "a note\n";
|
|
|
2307 18: @}
|
|
|
2308 19: @}
|
|
|
2309
|
|
|
2310 @end group
|
|
|
2311 @end example
|
|
|
2312
|
|
|
2313 @cindex modifier syntactic symbol
|
|
|
2314 The lines to note in this example include:
|
|
|
2315
|
|
|
2316 @itemize @bullet
|
|
|
2317
|
|
|
2318 @item
|
|
|
2319 line 2 which is assigned the @code{ansi-funcdecl-cont} syntax;
|
|
|
2320
|
|
|
2321 @item
|
|
|
2322 line 4 which is assigned both @code{defun-block-intro} @emph{and}
|
|
|
2323 @code{comment-intro} syntax @footnote{The @code{comment-intro} syntactic
|
|
|
2324 symbol is known generically as a @dfn{modifier} since it always appears
|
|
|
2325 on a syntactic analysis list with other symbols, and never has a
|
|
|
2326 relative buffer position.};
|
|
|
2327
|
|
|
2328 @item
|
|
|
2329 line 5 which is assigned @code{c} syntax;
|
|
|
2330
|
|
|
2331 @item
|
|
|
2332 @cindex syntactic whitespace
|
|
|
2333 line 6 which, even though it contains nothing but whitespace, is
|
|
|
2334 assigned @code{defun-block-intro}. Note that the appearance of the
|
|
|
2335 comment on lines 4 and 5 do not cause line 6 to be assigned
|
|
|
2336 @code{statement} syntax because comments are considered to be
|
|
|
2337 @dfn{syntactic whitespace}, which are essentially ignored when analyzing
|
|
|
2338 code;
|
|
|
2339
|
|
|
2340 @item
|
|
|
2341 line 8 which is assigned @code{string} syntax;
|
|
|
2342
|
|
|
2343 @item
|
|
|
2344 line 10 which is assigned @code{label} syntax;
|
|
|
2345
|
|
|
2346 @item
|
|
|
2347 line 11 which is assigned @code{block-open} syntax;
|
|
|
2348
|
|
|
2349 @item
|
|
|
2350 lines 12 and 14 which are assigned @code{cpp-macro} syntax;
|
|
|
2351
|
|
|
2352 @item
|
|
|
2353 line 17 which is assigned @code{stream-op} syntax @footnote{In C++ only.}.
|
|
|
2354
|
|
|
2355 @end itemize
|
|
|
2356
|
|
|
2357 In Objective-C buffers, there are three additional syntactic symbols
|
|
|
2358 assigned to various message calling constructs. Here's an example
|
|
|
2359 illustrating these:
|
|
|
2360 @example
|
|
|
2361 @group
|
|
|
2362
|
|
|
2363 1: - (void)setDelegate:anObject
|
|
|
2364 2: withStuff:stuff
|
|
|
2365 3: @{
|
|
|
2366 4: [delegate masterWillRebind:self
|
|
|
2367 5: toDelegate:anObject
|
|
|
2368 6: withExtraStuff:stuff];
|
|
|
2369 7: @}
|
|
|
2370
|
|
|
2371 @end group
|
|
|
2372 @end example
|
|
|
2373
|
|
|
2374 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
|
|
|
2375 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
|
|
|
2376 assigned @code{objc-method-call-cont} syntax.
|
|
|
2377
|
|
|
2378 Other syntactic symbols may be recognized by @code{cc-mode}, but these
|
|
|
2379 are more obscure and so I haven't included examples of them. These
|
|
|
2380 include: @code{knr-argdecl-intro}, @code{knr-argdecl}, and the
|
|
|
2381 @code{friend} modifier.
|
|
|
2382
|
|
|
2383 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2384 @node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top
|
|
|
2385 @comment node-name, next, previous,up
|
|
|
2386
|
|
|
2387 @chapter Performance Issues
|
|
|
2388 @cindex Performance Issues
|
|
|
2389 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2390
|
|
|
2391 C and it's derivative languages are highly complex creatures. Often,
|
|
|
2392 ambiguous code situations arise that require @code{cc-mode} to scan
|
|
|
2393 large portions of the buffer to determine syntactic context. Some
|
|
|
2394 pathological code can cause @code{cc-mode} to slow down considerably.
|
|
|
2395 This section identifies some of the coding styles to watch out for, and
|
|
|
2396 suggests some workarounds that you can use to improve performance.
|
|
|
2397
|
|
|
2398 Note that this is an area that will get a lot of attention in
|
|
|
2399 @code{cc-mode} version 5. The mode should end up being much faster, at
|
|
|
2400 the expense of dropping Emacs 18 support, owing to the implementation of
|
|
|
2401 syntactic analysis caching. This is the last release of @code{cc-mode}
|
|
|
2402 that will be compatible with Emacs 18.
|
|
|
2403
|
|
|
2404 Because @code{cc-mode} has to scan the buffer backwards from the current
|
|
|
2405 insertion point, and because C's syntax is fairly difficult to parse in
|
|
|
2406 the backwards direction, @code{cc-mode} often tries to find the nearest
|
|
|
2407 position higher up in the buffer from which to begin a forward scan.
|
|
|
2408 The farther this position is from the current insertion point, the
|
|
|
2409 slower the mode gets. Some coding styles can even force @code{cc-mode}
|
|
|
2410 to scan from the beginning of the buffer!
|
|
|
2411
|
|
|
2412 @findex beginning-of-defun
|
|
|
2413 @findex defun-prompt-regexp
|
|
|
2414 One of the simplest things you can do to reduce scan time, is make sure
|
|
|
2415 any brace that opens a top-level block construct always appears in the
|
|
|
2416 leftmost column. This is actually an Emacs constraint, as embodied in
|
|
|
2417 the @code{beginning-of-defun} function which @code{cc-mode} uses
|
|
|
2418 heavily. If you insist on hanging top-level open braces on the right
|
|
|
2419 side of the line, then you should set the variable
|
|
|
2420 @code{defun-prompt-regexp} to something reasonable @footnote{Note that
|
|
|
2421 this variable is only defined in Emacs 19.}, however that ``something
|
|
|
2422 reasonable'' is difficult to define, so @code{cc-mode} doesn't do it
|
|
|
2423 for you.
|
|
|
2424
|
|
|
2425 @cindex @file{cc-lobotomy.el} file
|
|
|
2426 You will probably notice pathological behavior from @code{cc-mode} when
|
|
|
2427 working in files containing large amounts of cpp macros. This is
|
|
|
2428 because @code{cc-mode} cannot quickly skip backwards over these lines,
|
|
|
2429 which do not contribute to the syntactic calculations. You'll probably
|
|
|
2430 also have problems if you are editing ``K&R'' C code, i.e. C code that
|
|
|
2431 does not use function prototypes. This is because there are ambiguities
|
|
|
2432 in the C syntax when K&R style argument lists are used, and
|
|
|
2433 @code{cc-mode} has to use a slower scan to determine what it's looking
|
|
|
2434 at.
|
|
|
2435
|
|
|
2436 @vindex c-recognize-knr-p
|
|
|
2437 @vindex recognize-knr-p (c-)
|
|
|
2438 For the latter problem, I would suggest converting to ANSI style
|
|
|
2439 protocols, and turning the variable @code{c-recognize-knr-p} to
|
|
|
2440 @code{nil} (this is it's default value for all modes).
|
|
|
2441
|
|
|
2442 @vindex cc-lobotomy-pith-list
|
|
|
2443 For the former problem, you might want to investigate some of the
|
|
|
2444 speed-ups provided for you in the file @file{cc-lobotomy.el}, which
|
|
|
2445 is part of the canonical @code{cc-mode} distribution. As mentioned
|
|
|
2446 previous, @code{cc-mode} always trades accuracy for speed, however it is
|
|
|
2447 recognized that sometimes you need speed and can sacrifice some accuracy
|
|
|
2448 in indentation. The file @file{cc-lobotomy.el} contains hacks that
|
|
|
2449 will ``dumb down'' @code{cc-mode} in some specific ways, making that
|
|
|
2450 trade-off of speed for accuracy. I won't go into details of its use
|
|
|
2451 here; you should read the comments at the top of the file, and look at
|
|
|
2452 the variable @code{cc-lobotomy-pith-list} for details.
|
|
|
2453
|
|
|
2454
|
|
|
2455 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2456 @node Frequently Asked Questions, Getting the latest cc-mode release, Performance Issues, Top
|
|
|
2457 @comment node-name, next, previous,up
|
|
|
2458
|
|
|
2459 @chapter Frequently Asked Questions
|
|
|
2460 @cindex Frequently Asked Questions
|
|
|
2461 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2462
|
|
|
2463 @kindex C-x h
|
|
|
2464 @kindex ESC C-\
|
|
|
2465 @kindex ESC C-x
|
|
|
2466 @kindex C-c C-q
|
|
|
2467 @kindex ESC C-q
|
|
|
2468 @kindex ESC C-u
|
|
|
2469 @kindex RET
|
|
|
2470 @kindex LFD
|
|
|
2471 @findex newline-and-indent
|
|
|
2472 @quotation
|
|
|
2473
|
|
|
2474 @strong{Q.} @emph{How do I re-indent the whole file?}
|
|
|
2475
|
|
|
2476 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
|
|
|
2477 buffer. Then hit @kbd{@key{ESC} C-\}.
|
|
|
2478 @sp 2
|
|
|
2479
|
|
|
2480 @strong{Q.} @emph{How do I re-indent the entire function?
|
|
|
2481 @kbd{@key{ESC} C-x} doesn't work.}
|
|
|
2482
|
|
|
2483 @strong{A.} @kbd{@key{ESC} C-x} is reserved for future Emacs use.
|
|
|
2484 To re-indent the entire function hit @kbd{C-c C-q}.
|
|
|
2485 @sp 2
|
|
|
2486
|
|
|
2487 @strong{Q.} @emph{How do I re-indent the current block?}
|
|
|
2488
|
|
|
2489 @strong{A.} First move to the brace which opens the block with
|
|
|
2490 @kbd{@key{ESC} C-u}, then re-indent that expression with
|
|
|
2491 @kbd{@key{ESC} C-q}.
|
|
|
2492 @sp 2
|
|
|
2493
|
|
|
2494 @strong{Q.} @emph{Why doesn't the @key{RET} key indent the line to
|
|
|
2495 where the new text should go after inserting the newline?}
|
|
|
2496
|
|
|
2497 @strong{A.} Emacs' convention is that @key{RET} just adds a newline,
|
|
|
2498 and that @key{LFD} adds a newline and indents it. You can make
|
|
|
2499 @key{RET} do this too by adding this to your
|
|
|
2500 @code{c-mode-common-hook} (see the sample @file{.emacs} file
|
|
|
2501 @ref{Sample .emacs File}):
|
|
|
2502 @example
|
|
|
2503
|
|
|
2504 (define-key c-mode-map "\C-m" 'newline-and-indent)
|
|
|
2505
|
|
|
2506 @end example
|
|
|
2507
|
|
|
2508 This is a very common question. @code{:-)} If you want this to be the
|
|
|
2509 default behavior, don't lobby me, lobby RMS!
|
|
|
2510 @sp 2
|
|
|
2511
|
|
|
2512 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
|
|
|
2513 in my @file{.emacs} file but I get an error saying that
|
|
|
2514 @code{c-set-offset}'s function definition is void.}
|
|
|
2515
|
|
|
2516 @strong{A.} This means that @code{cc-mode} wasn't loaded into your
|
|
|
2517 Emacs session by the time the @code{c-set-offset} call was reached,
|
|
|
2518 mostly likely because @code{cc-mode} is being autoloaded. Instead
|
|
|
2519 of putting the @code{c-set-offset} line in your top-level
|
|
|
2520 @file{.emacs} file, put it in your @code{c-mode-common-hook}, or
|
|
|
2521 simply add the following to the top of your @file{.emacs} file:
|
|
|
2522 @example
|
|
|
2523
|
|
|
2524 (require 'cc-mode)
|
|
|
2525
|
|
|
2526 @end example
|
|
|
2527
|
|
|
2528 See the sample @file{.emacs} file @ref{Sample .emacs File} for
|
|
|
2529 details.
|
|
|
2530
|
|
|
2531 @strong{Q.} @emph{How do I make strings, comments, keywords, and other
|
|
|
2532 constructs appear in different colors, or in bold face, etc.?}
|
|
|
2533
|
|
|
2534 @strong{A.} ``Syntax Colorization'' is an Emacs 19 feature, controlled
|
|
|
2535 by @code{font-lock-mode}. It is not part of @code{cc-mode}.
|
|
|
2536
|
|
|
2537 @end quotation
|
|
|
2538
|
|
|
2539
|
|
|
2540 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2541 @node Getting the latest cc-mode release, Sample .emacs File, Frequently Asked Questions, Top
|
|
|
2542 @comment node-name, next, previous,up
|
|
|
2543
|
|
|
2544 @chapter Getting the latest @code{cc-mode} release
|
|
|
2545 @cindex Getting the latest @code{cc-mode} release
|
|
|
2546 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2547
|
|
|
2548 @code{cc-mode} is now distributed with both Emacs 19 and XEmacs 19, so
|
|
|
2549 you would typically just use the version that comes with your Emacs.
|
|
|
2550 Users of older versions of Emacs can get the latest release from this
|
|
|
2551 URL:
|
|
|
2552
|
|
|
2553 @example
|
|
|
2554
|
|
|
2555 @code{ftp://ftp.python.org/pub/emacs/cc-mode.tar.gz}
|
|
|
2556
|
|
|
2557 @end example
|
|
|
2558
|
|
|
2559 Note that this is a ``gzipped'' tar file.
|
|
|
2560
|
|
|
2561 If you do not have anonymous ftp access, you can get the distribution
|
|
|
2562 through an anonymous ftp-to-mail gateway, such as the one run by DEC at
|
|
|
2563 @code{ftpmail@@decwrl.dec.com}. To get @code{cc-mode} via email, send
|
|
|
2564 the following message in the body of your mail to that address:
|
|
|
2565 @example
|
|
|
2566
|
|
|
2567 reply <a valid net address back to you>
|
|
|
2568 connect ftp.python.org
|
|
|
2569 binary
|
|
|
2570 uuencode
|
|
|
2571 chdir pub/emacs
|
|
|
2572 get cc-mode.tar.gz
|
|
|
2573
|
|
|
2574 @end example
|
|
|
2575 @noindent
|
|
|
2576 or just send the message "help" for more information on ftpmail.
|
|
|
2577 Response times will vary with the number of requests in the queue.
|
|
|
2578
|
|
|
2579 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2580 @node Sample .emacs File, Requirements, Getting the latest cc-mode release, Top
|
|
|
2581 @comment node-name, next, previous,up
|
|
|
2582
|
|
|
2583 @chapter Sample @file{.emacs} file
|
|
|
2584 @cindex Sample @file{.emacs} file
|
|
|
2585 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2586
|
|
|
2587 @example
|
|
|
2588 ;; Here's a sample .emacs file that might help you along the way. Just
|
|
|
2589 ;; copy this region and paste it into your .emacs file. You may want to
|
|
|
2590 ;; change some of the actual values.
|
|
|
2591
|
|
|
2592 (defconst my-c-style
|
|
|
2593 '((c-tab-always-indent . t)
|
|
|
2594 (c-comment-only-line-offset . 4)
|
|
|
2595 (c-hanging-braces-alist . ((substatement-open after)
|
|
|
2596 (brace-list-open)))
|
|
|
2597 (c-hanging-colons-alist . ((member-init-intro before)
|
|
|
2598 (inher-intro)
|
|
|
2599 (case-label after)
|
|
|
2600 (label after)
|
|
|
2601 (access-label after)))
|
|
|
2602 (c-cleanup-list . (scope-operator
|
|
|
2603 empty-defun-braces
|
|
|
2604 defun-close-semi))
|
|
|
2605 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
|
|
|
2606 (substatement-open . 0)
|
|
|
2607 (case-label . 4)
|
|
|
2608 (block-open . 0)
|
|
|
2609 (knr-argdecl-intro . -)))
|
|
|
2610 (c-echo-syntactic-information-p . t)
|
|
|
2611 )
|
|
|
2612 "My C Programming Style")
|
|
|
2613
|
|
|
2614 ;; Customizations for all of c-mode, c++-mode, and objc-mode
|
|
|
2615 (defun my-c-mode-common-hook ()
|
|
|
2616 ;; add my personal style and set it for the current buffer
|
|
|
2617 (c-add-style "PERSONAL" my-c-style t)
|
|
|
2618 ;; offset customizations not in my-c-style
|
|
|
2619 (c-set-offset 'member-init-intro '++)
|
|
|
2620 ;; other customizations
|
|
|
2621 (setq tab-width 8
|
|
|
2622 ;; this will make sure spaces are used instead of tabs
|
|
|
2623 indent-tabs-mode nil)
|
|
|
2624 ;; we like auto-newline and hungry-delete
|
|
|
2625 (c-toggle-auto-hungry-state 1)
|
|
|
2626 ;; keybindings for C, C++, and Objective-C. We can put these in
|
|
|
2627 ;; c-mode-map because c++-mode-map and objc-mode-map inherit it
|
|
|
2628 (define-key c-mode-map "\C-m" 'newline-and-indent)
|
|
|
2629 )
|
|
|
2630
|
|
|
2631 ;; the following only works in Emacs 19
|
|
|
2632 ;; Emacs 18ers can use (setq c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
2633 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
|
|
|
2634 @end example
|
|
|
2635
|
|
|
2636 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2637 @node Requirements, Limitations and Known Bugs, Sample .emacs File, Top
|
|
|
2638 @comment node-name, next, previous,up
|
|
|
2639 @chapter Requirements
|
|
|
2640 @cindex Requirements
|
|
|
2641 @comment * Requirements
|
|
|
2642 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2643
|
|
|
2644 @cindex reporter.el
|
|
|
2645 @file{cc-mode.el} requires @file{reporter.el} for submission of bug
|
|
|
2646 reports. @file{reporter.el} is distributed with the latest Emacs 19s.
|
|
|
2647 Here is the Emacs Lisp Archive anonymous ftp'ing record for those of you
|
|
|
2648 who are using older Emacsen.
|
|
|
2649
|
|
|
2650 @comment * Here's the Emacs Lisp Archive information for @file{reporter.el}:
|
|
|
2651 @example
|
|
|
2652
|
|
|
2653 GNU Emacs Lisp Code Directory Apropos -- "reporter"
|
|
|
2654 "~/" refers to archive.cis.ohio-state.edu:/pub/gnu/emacs/elisp-archive/
|
|
|
2655
|
|
|
2656 reporter (2.12) 06-Jul-1994
|
|
|
2657 Barry A. Warsaw, <bwarsaw@@cnri.reston.va.us>
|
|
|
2658 ~/misc/reporter.el.Z
|
|
|
2659 Customizable bug reporting of lisp programs.
|
|
|
2660
|
|
|
2661 @end example
|
|
|
2662
|
|
|
2663 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2664 @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Requirements, Top
|
|
|
2665 @comment node-name, next, previous,up
|
|
|
2666 @chapter Limitations and Known Bugs
|
|
|
2667 @cindex Limitations and Known Bugs
|
|
|
2668 @comment * Limitations and Known Bugs
|
|
|
2669 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2670
|
|
|
2671 @itemize @bullet
|
|
|
2672 @item
|
|
|
2673 Multi-line macros are not handled properly.
|
|
|
2674
|
|
|
2675 @item
|
|
|
2676 Re-indenting large regions or expressions can be slow.
|
|
|
2677
|
|
|
2678 @item
|
|
|
2679 Use with Emacs 18 can be slow and annoying. You should seriously
|
|
|
2680 consider upgrading to Emacs 19.
|
|
|
2681
|
|
|
2682 @item
|
|
|
2683 There is still some weird behavior when filling C block comments.
|
|
|
2684 My suggestion is to check out add-on fill packages such as
|
|
|
2685 @code{filladapt}, available at the elisp archive.
|
|
|
2686
|
|
|
2687 @cindex inline-close
|
|
|
2688 @kindex TAB
|
|
|
2689 @item
|
|
|
2690 Lines following @code{inline-close} braces which hang ``after'' do not
|
|
|
2691 line up correctly. Hit @kbd{TAB} to reindent the line.
|
|
|
2692
|
|
|
2693 @end itemize
|
|
|
2694
|
|
|
2695 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2696 @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top
|
|
|
2697 @comment node-name, next, previous,up
|
|
|
2698 @chapter Mailing Lists and Submitting Bug Reports
|
|
|
2699 @cindex Mailing Lists and Submitting Bug Reports
|
|
|
2700 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2701
|
|
|
2702 @kindex C-c C-b
|
|
|
2703 @findex c-submit-bug-report
|
|
|
2704 @findex submit-bug-report (c-)
|
|
|
2705 @cindex beta testers mailing list
|
|
|
2706 @cindex announcement mailing list
|
|
|
2707 To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report})
|
|
|
2708 command. This provides vital information I need to reproduce your
|
|
|
2709 problem. Make sure you include a concise, but complete code example.
|
|
|
2710 Please try to boil your example down to just the essential code needed
|
|
|
2711 to reproduce the problem, and include an exact recipe of steps needed to
|
|
|
2712 expose the bug. Be especially sure to include any code that appears
|
|
|
2713 @emph{before} your bug example.
|
|
|
2714
|
|
|
2715 Bug reports are now to be sent to @code{bug-gnu-emacs@@prep.ai.mit.edu}
|
|
|
2716 which is mirrored on the Usenet newsgroup @code{gnu.emacs.bug}. Other
|
|
|
2717 questions and suggestions should be mailed to
|
|
|
2718 @code{help-gnu-emacs@@prep.ai.mit.edu} which is mirrored on
|
|
|
2719 @code{gnu.emacs.help}.
|
|
|
2720
|
|
|
2721 Note that the @code{cc-mode} Majordomo mailing lists have been
|
|
|
2722 disbanded! With the inclusion of @code{cc-mode} in both of the latest
|
|
|
2723 flavors of Emacs 19, the need for them has ended.
|
|
|
2724
|
|
|
2725 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2726 @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top
|
|
|
2727 @comment node-name, next, previous, up
|
|
|
2728 @unnumbered Concept Index
|
|
|
2729 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2730
|
|
|
2731 @printindex cp
|
|
|
2732
|
|
|
2733
|
|
|
2734 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2735 @node Command Index, Key Index, Concept Index, Top
|
|
|
2736 @comment node-name, next, previous, up
|
|
|
2737 @unnumbered Command Index
|
|
|
2738 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2739
|
|
|
2740 @ifinfo
|
|
|
2741
|
|
|
2742 @end ifinfo
|
|
|
2743 Since all @code{cc-mode} commands are prepended with the string
|
|
|
2744 @samp{c-}, each appears under its @code{c-<thing>} name and its
|
|
|
2745 @code{<thing> (c-)} name.
|
|
|
2746 @iftex
|
|
|
2747 @sp 2
|
|
|
2748 @end iftex
|
|
|
2749 @printindex fn
|
|
|
2750
|
|
|
2751
|
|
|
2752 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2753 @node Key Index, Variable Index, Command Index, Top
|
|
|
2754 @comment node-name, next, previous, up
|
|
|
2755 @unnumbered Key Index
|
|
|
2756 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2757
|
|
|
2758 @printindex ky
|
|
|
2759
|
|
|
2760
|
|
|
2761 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2762 @node Variable Index, , Key Index, Top
|
|
|
2763 @comment node-name, next, previous, up
|
|
|
2764 @unnumbered Variable Index
|
|
|
2765 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
2766
|
|
|
2767 @ifinfo
|
|
|
2768
|
|
|
2769 @end ifinfo
|
|
|
2770 Since all @code{cc-mode} variables are prepended with the string
|
|
|
2771 @samp{c-}, each appears under its @code{c-<thing>} name and its
|
|
|
2772 @code{<thing> (c-)} name.
|
|
|
2773 @iftex
|
|
|
2774 @sp 2
|
|
|
2775 @end iftex
|
|
|
2776 @printindex vr
|
|
|
2777 @summarycontents
|
|
|
2778 @contents
|
|
|
2779 @bye
|
