-
Notifications
You must be signed in to change notification settings - Fork 7
/
customize_c.html
485 lines (453 loc) · 32.9 KB
/
customize_c.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
<!DOCTYPE html>
<html lang='en'>
<head>
<meta charset='utf-8'>
<title>
How to learn Emacs :: cc-mode customization
</title>
<link href='emacs.css' media='all' rel='stylesheet'>
</head>
<body>
<div id='sidebar'>
<div id='info'>
<h1>How to learn Emacs</h1>
<p>By <a href="http://david.rothlis.net">David Röthlisberger</a>.<br/>
Comments welcome at <a href="mailto:david@rothlis.net?subject=How%20to%20learn%20Emacs">david@rothlis.net</a>.<br/>
Last updated 8 Apr 2012.</p>
</div>
<div id='toc'>
<!-- Table of Contents -->
<ul>
<li><a href='howtolearn.html'>1. About this guide to Emacs</a></li>
<li><a href='why.html'>2. Why Emacs</a></li>
</ul>
<p>—Basic usage—</p>
<ul>
<li><a href='install.html'>3. Install the right Emacs</a></li>
<li><a href='tutorial.html'>4. The very basics</a></li>
<li><a href='basic_c.html'>5. Basic Unix/C workflow</a></li>
</ul>
<p>—Basic customisation—</p>
<ul>
<li class='current'>6. cc-mode customization
<ul>
<li><a href="#style">House coding style</a></li>
<li><a href="#elisp">Emergency elisp</a></li>
<li><a href="#indentation">Configuring indentation</a></li>
<li><a href="#setq">Setting variables from elisp code</a></li>
<li><a href="#init">Init file</a></li>
<li><a href="#hooks">Hooks</a></li>
<li><a href="#style-system">The cc-mode style system</a></li>
<li><a href="#keys">Binding keys</a></li>
<li><a href="#auto-mode">Associating file extensions with an <a class='glossary' href='glossary.html#majormode'>editing mode</a></a></li>
<li><a href="#homework">Homework</a></li>
</ul>
</li>
<li><a href='customize_colors.html'>7. Fix that awful color scheme</a></li>
<li><a href='customize_general.html'>8. General customization</a></li>
</ul>
<p>—Miscellaneous—</p>
<ul>
<li><a href='info.html'>9. Info documentation</a></li>
<li><a href='contribute_emacs.html'>10. Contributing to Emacs</a></li>
</ul>
<p>—Appendices—</p>
<ul>
<li><a href='ergonomics.html'>A. Ergonomics</a></li>
<li><a href='osx.html'>B. OS X</a></li>
<li><a href='contribute_guide.html'>C. Contributing to this guide</a></li>
<li><a href='glossary.html'>D. Glossary</a></li>
</ul>
</div>
<p>Copyright © 2012 <a href="http://david.rothlis.net">David Röthlisberger</a>.<br/>
This guide is released under the<br/>
<a rel="license" href="http://www.gnu.org/copyleft/fdl.html">GNU
Free Documentation License</a>.</p>
</div>
<div id='content2'>
<!-- Contents -->
<h1>cc-mode customization</h1>
<p>I should probably lead you through the relevant parts of the <a href="http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html">Emacs</a>, <a href="http://www.gnu.org/software/emacs/manual/html_node/elisp/index.html">Emacs
Lisp</a>,
and <a href="http://www.gnu.org/software/emacs/manual/html_node/ccmode/index.html">CC Mode</a> manuals,
but they’re just. so. <em>long</em>! The mere table of contents for the Emacs manual
is longer than our previous “Unix/C workflow” chapter.<a id='fnref1' href='#fn1' class='footnote'>[1]</a></p>
<p>Instead I’ll show you how I try to find the information I need from the Emacs
source code (most of which, thankfully, is in Lisp rather than C). The manuals
I dissed a moment ago <em>are</em> incredibly useful. It is cause for wonder that an
open-source project has produced such comprehensive documentation! But it is
<em>impossible</em> to read those manuals cover-to-cover; you must learn how to
efficiently find the right information. We’ve already covered the basic tools
for that, and now we will exercise them a lot more.</p>
<p>By the way, <code>c-mode</code>, <code>c++-mode</code>, <code>objc-mode</code>, <code>java-mode</code>, and a few others
are all aliases for <code>cc-mode</code>, but with slight configuration changes to support
the respective languages. From here on I’ll use the name <code>cc-mode</code>.</p>
<h2 id='style'>House coding style</h2>
<p>Are you supposed to indent with 2, 3, 4 or 8 spaces, or with tabs? How big is
a tab? Whatever you want, I’m going to assume it’s <em>not</em> the indentation that
cc-mode provides by default, so that we can walk through the procedure for
changing it.</p>
<div class='do'>
<p>Visit (open) a C or C++ file (you can use <code>readline/examples/rl.c</code> from the
previous chapter).</p>
</div>
<p>Pressing <code>TAB</code> anywhere on a line indents it to the appropriate position
according to the current indentation rules (to insert a literal tab, use
<code><a class='glossary' href='glossary.html#keys'>C-q</a></code>, a.k.a. <code>quoted-insert</code>).</p>
<p>Let’s find out what Emacs does behind the scenes when we press <code>TAB</code>:</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h k TAB</a></code></p>
</div>
<div class='window'>TAB runs the command c-indent-line-or-region,
which is an interactive compiled Lisp function in `<span class="button">cc-cmds.el</span>'.
 </div>
<div class='modeline'>-U:%%- <b>*Help*</b> Top L1 (Help View)-----------------------------------------------</div>
<div class='echoarea'><p>Type C-x 1 to delete the help <a class='glossary' href='glossary.html#windows'>window</a>.</p></div>
<p>If you don’t see the link to <code>cc-cmds.el</code>, then you don’t have the elisp
sources installed. Use your system’s package manager to install the <code>emacs-el</code>
package and try again.</p>
<div class='do'>
<p>Follow the link to <code>cc-cmds.el</code>. This will position you right where
<code>c-indent-line-or-region</code> is defined. Bring the whole definition into view
(<code><a class='glossary' href='glossary.html#keys'>C-M-l</a></code>) if necessary.</p>
</div>
<div class='window default'>(<span class="keyword">defun</span> <span class="function-name">c-indent-line-or-region</span> (<span class="type">&optional</span> arg region)
 <span class="doc">"Indent active region, current line, or block starting on this line.
In Transient Mark mode, when <a class='glossary' href='glossary.html#region'>the region</a> is active, reindent <a class='glossary' href='glossary.html#region'>the region</a>.
Otherwise, with a prefix argument, rigidly reindent the expression
starting on the current line.
Otherwise reindent just the current line."</span>
 (interactive
 (list current-prefix-arg (use-region-p)))
 (<span class="keyword">if</span> region
 (c-indent-region (region-beginning) (region-end))
 (c-indent-command arg)))

</div>
<h2 id='elisp'>Emergency elisp</h2>
<p>A brief parenthesis is needed to explain the above code. Let’s start with the
<code>if</code> statement at the end:</p>
<div class='window default'> <span class="region">(<span class="keyword">if</span> region
 (c-indent-region (region-beginning) (region-end))
 (c-indent-command arg))</span>)
</div>
<p>For clarity, let’s simplify it to:</p>
<div class='window default'> (<span class="keyword">if</span> region
 a
 b)
</div>
<p>If you still don’t understand what that means, pretend that <code>if</code> is actually a
function, and that it looks like this:</p>
<div class='window default'> <span class="keyword">if</span>(region, a, b)
</div>
<p>(Moving that parenthesis to the <em>left</em> of the function is probably the largest
single barrier to Lisp’s adoption by the rest of the world.)<a id='fnref2' href='#fn2' class='footnote'>[2]</a></p>
<div class='do'>
<p>What do the three arguments <code>region</code>, <code>a</code> and <code>b</code> mean? Make a guess, and
then check the answer at <code><a class='glossary' href='glossary.html#keys'>C-h f if</a></code>.</p>
</div>
<p>The definitions of <em><code>COND</code></em>, <em><code>THEN</code></em> and <em><code>ELSE</code></em> should be pretty clear. But
what does it mean by “<code>if</code> is a special form”?</p>
<p>It turns out that <code>if</code> isn’t a regular function. The elisp rule for evaluation
of “normal” forms—where “form” means a parenthesized “shape” like <code>(a b c)</code> or
<code>(a b (c d))</code>—is to evaluate each argument, and then pass the resulting values
to the function.</p>
<p>Let’s consider the function <code>+</code> (elisp doesn’t have special infix operators, so
<code>+</code> is just a function). If <code>x</code> is a variable containing the value <code>5</code>, and <code>y</code>
is a variable containing the value <code>2</code>, then the following two expressions are
identical:</p>
<div class='window default'> (+ x y)
 (+ 5 2)
</div>
<p>The function <code>+</code> never sees <code>x</code>; it only sees <code>5</code>.</p>
<div class='do'>
<p>Evaluate the form <code>(+ 5 2)</code>: Switch to the <code>*scratch*</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>, type <code>(+ 5 2)</code>
on a line of its own, and press <code><a class='glossary' href='glossary.html#keys'>C-M-x</a></code> to evaluate the form and display the
result in the <a class='glossary' href='glossary.html#echoarea'>echo area</a>.</p>
</div>
<p>The very first element in the form (<code>+</code>, in this case) gets evaluated too. <code>+</code>
is actually a variable<a id='fnref3' href='#fn3' class='footnote'>[3]</a> whose value is the function that adds numbers.</p>
<p>Anyway, back to <code>if</code>. <code>if</code> is a “special” form, which means that the elisp
interpreter treats <code>if</code> as a special case. Upon reflection, it is obvious that
the normal function evaluation rules are not suitable for <code>if</code>: We wouldn’t
want to evaluate <em><code>ELSE</code></em>, with its possible side-effects, when <em><code>COND</code></em> is
“true” (non-nil).</p>
<p>All this is explained in the Emacs Lisp manual:</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S if</a></code></p>
<p>In the <code>*info*</code> <a class='glossary' href='glossary.html#buffers'>buffer</a> press <code>i</code> (for <code>i</code>ndex) and enter <code>special forms</code>.</p>
</div>
<div class='do'>
<p>Go back to the <code>cc-cmds.el.gz</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>.</p>
<p>Enable the <code>eldoc</code> <a class='glossary' href='glossary.html#minormode'>minor mode</a> (<code><a class='glossary' href='glossary.html#keys'>M-x eldoc-mode</a></code>). Now positioning <a class='glossary' href='glossary.html#region'>the point</a>
over the <code>if</code> statement will show some brief documentation in the <a class='glossary' href='glossary.html#echoarea'>echo area</a>.</p>
<p>Enable <code>show-paren-mode</code> too. This should help clarify where the <em><code>THEN</code></em> and
<em><code>ELSE</code></em> clauses begin and end.</p>
</div>
<p>Now, back up to the <code>defun</code>:</p>
<div class='window default'>(<span class="keyword">defun</span> <span class="function-name">c-indent-line-or-region</span> (<span class="type">&optional</span> arg region)
 <span class="doc">"Indent active region, current line, or block starting on this line.
In Transient Mark mode, when <a class='glossary' href='glossary.html#region'>the region</a> is active, reindent <a class='glossary' href='glossary.html#region'>the region</a>.
Otherwise, with a prefix argument, rigidly reindent the expression
starting on the current line.
Otherwise reindent just the current line."</span>
 (interactive
 (list current-prefix-arg (use-region-p)))
 (<span class="keyword">if</span> region
 (c-indent-region (region-beginning) (region-end))
 (c-indent-command arg)))
</div>
<div class='do'>
<p>You now have three ways to get help on <code>defun</code>: <code>eldoc</code>’s summary in the echo
area, the reference provided by <code><a class='glossary' href='glossary.html#keys'>C-h f</a></code>, and the more comprehensive Info
manual at <code><a class='glossary' href='glossary.html#keys'>C-h S</a></code>. Take your pick.</p>
</div>
<p>If you run across the word “lambda”, it’s the same as the “function” keyword
in javascript for an anonymous function.</p>
<p>To reiterate:</p>
<ul>
<li><code>defun</code> defines a function named <em><code>NAME</code></em>.</li>
<li><em><code>ARGLIST</code></em> is a list of arguments for the function. In elisp, a list is
enclosed in parens: <code>(a b c)</code>. In this case it isn’t evaluated as a function
call, because <code>defun</code> is a special form that treats this particular list in a
special way. When <code>defun</code>ing a function that takes no arguments, <em><code>ARGLIST</code></em>
would be the empty list <code>()</code>.</li>
<li>The optional <em><code>DOCSTRING</code></em> is used by the <code><a class='glossary' href='glossary.html#keys'>C-h f</a></code> help system (yes, even for
functions you define yourself!).</li>
<li><em><code>BODY</code></em> is one or more lists that are evaluated when you <em>call</em> the
function.</li>
<li>…except for the <code>(interactive ...)</code> form.</li>
</ul>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S interactive</a></code></p>
</div>
<p>Don’t get too bogged-down by the explanation; reading the first two paragrahs
is enough. Learn to find <em>just</em> the information you need, or you will be easily
overwhelmed. Right now we don’t need to know how to <em>use</em> <code>interactive</code>, only
what it <em>means</em>.</p>
<h2 id='indentation'>Configuring indentation</h2>
<p>So. <code>c-indent-line-or-region</code> is a function that optionally takes arguments
<code>arg</code> and <code>region</code>, which, when the function is called interactively (for
example by pressing <code>TAB</code>), are set to the prefix argument (if specified with
<code><a class='glossary' href='glossary.html#keys'>C-u</a></code> or similar) and “true” if <a class='glossary' href='glossary.html#region'>the region</a> is active.</p>
<p>Right now we care about indentation when operating not on <a class='glossary' href='glossary.html#region'>the region</a> but on a
single line (i.e. <code>region</code> is <code>nil</code>), so let’s look at the <em><code>ELSE</code></em> clause:</p>
<div class='window default'> (<span class="keyword">if</span> region
 (c-indent-region (region-beginning) (region-end))
 <span class="region">(c-indent-command arg)</span>)
</div>
<div class='do'>
<p>Use <code>find-function</code> to jump to the definition of <code>c-indent-command</code>.</p>
</div>
<p>This is a long and scary function, but luckily it has a good documentation
string. Now that we know the name of this function, we can view the same
documentation in a help <a class='glossary' href='glossary.html#buffers'>buffer</a>, with <code><a class='glossary' href='glossary.html#keys'>C-h f c-indent-command</a></code>.</p>
<p>The documentation mentions a couple of interesting variables: <code>c-basic-offset</code>
and <code>indent-tabs-mode</code>.</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h v c-basic-offset</a></code></p>
</div>
<p>That talks about “buffer-local” and “file local” variables. What?</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S buffer-local</a></code></p>
</div>
<div class='do'>
<p>From the elisp Info node for Buffer-Local Variables, search for “file local”
(you can use <code><a class='glossary' href='glossary.html#keys'>C-s</a></code> or the index <code>i</code>).</p>
</div>
<p>As you can see you sometimes have to try different searches to find the right
information. “Buffer-local” happened to be in the index, so the symbol search
(<code><a class='glossary' href='glossary.html#keys'>C-h S</a></code>) found it; “File local” has a space, but the symbol search doesn’t
allow spaces, so you had to search from within the Info <a class='glossary' href='glossary.html#buffers'>buffer</a> itself. You
could also have gone up (<code>u</code>) from the “Buffer-Local Variables” Info node and
scanned the “Variables” table of contents.</p>
<p>Let’s check the current value of <code>c-basic-offset</code>:</p>
<div class='do'>
<p>Switch to <a class='glossary' href='glossary.html#buffers'>buffer</a> <code>rl.c</code> (<code>c-basic-offset</code> is buffer-local, so it matters
which <a class='glossary' href='glossary.html#buffers'>buffer</a> we’re in).</p>
<p><code><a class='glossary' href='glossary.html#keys'>M-x eval-expression RET c-basic-offset RET</a></code></p>
</div>
<p>Now change it to 4:</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>M-x set-variable c-basic-offset 4</a></code></p>
<p>Find a line to re-indent and press <code>TAB</code>.</p>
</div>
<div class='do'>
<p>Repeat the same investigation with variable <code>indent-tabs-mode</code>.</p>
</div>
<h2 id='setq'>Setting variables from elisp code</h2>
<div class='do'>
<p>Switch to the <code>*scratch*</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>.</p>
</div>
<p>Anything starting with a <code>;</code> is a comment.</p>
<div class='do'>
<p>Type in this form and evaluate it with <code><a class='glossary' href='glossary.html#keys'>C-M-x</a></code>:</p>
<p><code>(set indent-tabs-mode nil)</code></p>
</div>
<p>You triggered an error, and Emacs brings up the backtrace in an elisp debugger.
You tried to set a constant to <code>nil</code>, which is clearly an error.</p>
<div class='do'>
<p>Explain why this happened, with your knowledge of the previous value of
<code>indent-tabs-mode</code> and of the elisp rules for evaluating functions.</p>
</div>
<p>We can <em>quote</em> the name of the variable so that it doesn’t get evaluated:</p>
<div class='do'>
<p><code>(set 'indent-tabs-mode nil)</code></p>
</div>
<p>Read more about quoting:</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S quote</a></code></p>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S setq</a></code></p>
</div>
<p>The following forms do exactly the same; the preferred form is <code>setq</code>.</p>
<div class='window default'>(set 'indent-tabs-mode nil)
(set (quote indent-tabs-mode) nil)
(setq indent-tabs-mode nil)
</div>
<p>One last thing: <code>indent-tabs-mode</code> is buffer-local, so setting it here only
affects the <code>*scratch*</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>. To make the change global, you must use
<code>setq-default</code>.</p>
<h2 id='init'>Init file</h2>
<p>Your changes to these variables will be lost when you restart Emacs. You need
to put your settings into an initialization file that Emacs will load each time
it starts.</p>
<div class='do'>
<p>In the Emacs manual (<code><a class='glossary' href='glossary.html#keys'>C-h r</a></code>) table of contents, search for “init file” and
read the first paragraph.</p>
</div>
<p>There are several places you can put your init file; I suggest the one that
goes inside the <code>~/.emacs.d</code> directory, so you can organize your customizations
by keeping multiple elisp files in the same directory, and loading them from
the main init file. Put this directory under version control.</p>
<div class='do'>
<p>Visit (open) the init file you’ve chosen (if the file doesn’t exist, Emacs
will create it when you save the <a class='glossary' href='glossary.html#buffers'>buffer</a>).</p>
</div>
<div class='do'>
<p>Add the following lines:</p>
<p><code>(setq-default c-basic-offset 4)</code><br/>
<code>(setq-default indent-tabs-mode nil)</code></p>
</div>
<p>(or whatever values you have chosen).</p>
<div class='do'>
<p>Restart Emacs, visit <code>rl.c</code>, and verify that your settings are in effect.</p>
</div>
<h2 id='hooks'>Hooks</h2>
<p>By default, <code>cc-mode</code> automatically re-indents the line whenever you type a
character like <code>;</code> or <code>}</code>. These are called <a href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Electric-C.html">“electric characters”</a> and
you can disable this behavior in a particular <a class='glossary' href='glossary.html#buffers'>buffer</a> with
<code>c-toggle-electric-state</code> (<code><a class='glossary' href='glossary.html#keys'>C-c C-l</a></code>).</p>
<p>To always disable electric characters we can have Emacs call
<code>c-toggle-electric-state</code> each time it loads <code>cc-mode</code>.</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h m</a></code> (from the <code>rl.c</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>, or any other <code>cc-mode</code> <a class='glossary' href='glossary.html#buffers'>buffer</a>) to find out
the names of the hooks provided by <code>cc-mode</code>.</p>
</div>
<p>A <a href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a>
is a variable containing a list of functions to be run, usually upon entry to a
particular <a class='glossary' href='glossary.html#majormode'>editing mode</a>. For C code we have two hooks: One for all of
<code>cc-mode</code>’s supported languages, and one just for C. We’ll use the first one,
<code>c-mode-common-hook</code>.</p>
<div class='do'>
<p>Add the following to your init file:</p>
<div class='window default'>(<span class="keyword">defun</span> <span class="function-name">my-disable-electric-indentation</span> ()
 <span class="doc">"Stop ';', '}', etc. from re-indenting the current line."</span>
 (c-toggle-electric-state -1))
(add-hook 'c-mode-common-hook 'my-disable-electric-indentation)
</div>
</div>
<p>First we defined a function that takes no arguments and calls
<code>(c-toggle-electric-state -1)</code>. Then we added the function to the
<code>c-mode-common-hook</code>.</p>
<p>The <code>-1</code> argument tells <code>c-toggle-electric-state</code> to disable, rather than
toggle, the electric behavior (I learned this from <code><a class='glossary' href='glossary.html#keys'>C-h f</a>
c-toggle-electric-state</code>; some functions might want <code>nil</code>, but this one wanted
a negative number).</p>
<p>You could add an anonymous function to a hook directly:</p>
<div class='window default'>(add-hook 'c-mode-common-hook
 (<span class="keyword">lambda</span> () (c-toggle-electric-state -1)))
</div>
<p>but then you have no way of referring to the function by name, so you can’t
remove it from the hook with <code>remove-hook</code>.</p>
<h2 id='style-system'>The cc-mode style system</h2>
<p>There is more to coding style than the size of indentation. Where should
opening braces go? Should they be indented too?</p>
<p>The <code><a class='glossary' href='glossary.html#keys'>C-h v</a></code> documentation for <code>c-basic-offset</code> mentioned a “style system”, and
referred us to <code>c-default-style</code>.</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h v c-default-style</a></code></p>
</div>
<div class='window default'>c-default-style is a variable defined in `<span class="button">cc-vars.el</span>'.
Its value is ((java-mode . "java")
 (awk-mode . "awk")
 (other . "gnu"))
</div>
<p>Elisp syntax for a list is <code>(a b c)</code>, and for a pair is <code>(a . b)</code>. Pairs are
called “cons cells” in lisp terminology, and you access the first element with
the function <code>car</code>, the second with the function <code>cdr</code> (pronounced
“could-er”).</p>
<p>So the value of <code>c-default-style</code> is a list containing 3 pairs; it’s used as a
lookup dictionary where <code>java-mode</code>, <code>awk-mode</code> and <code>other</code> are the keys, and
<code>"java"</code>, <code>"awk"</code> and <code>"gnu"</code> are the values (in this case, names of styles to
use for each of the <a class='glossary' href='glossary.html#majormode'>editing modes</a> represented by the keys). These lookup
dictionaries are called “alists”.</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h S alist</a></code></p>
</div>
<p>In your init file you could set <code>c-default-style</code> so that the default style for
<code>other</code><a id='fnref4' href='#fn4' class='footnote'>[4]</a> is something other than <code>"gnu"</code>.</p>
<p>If you need to customize anything (including <code>c-basic-offset</code> and
<code>indent-tabs-mode</code>) to something different than any of the built-in styles, I
recommend you define your own style: Thus if you work on different projects
with different styles, you will be able to switch easily (with <code>c-set-style</code>).
The way we set <code>c-basic-offset</code> earlier will <a href="http://www.gnu.org/software/emacs/manual/html_node/ccmode/Built_002din-Styles.html#index-User-style-294">automatically create a style
called “user”</a>.</p>
<p>For help see <a href="http://www.gnu.org/software/emacs/manual/html_node/ccmode/Config-Basics.html">“Configuration basics”</a>,
<a href="http://www.gnu.org/software/emacs/manual/html_node/ccmode/Customizing-Indentation.html">“Customizing indentation”</a>,
and <a href="http://www.gnu.org/software/emacs/manual/html_node/ccmode/Sample-_002eemacs-File.html">“Sample .emacs file”</a>
in the CC Mode Manual.</p>
<h2 id='keys'>Binding keys</h2>
<p>I often come across source code where one file expects tabs to equal 8 spaces,
and another file in the same directory—or even other lines within the same
file—want a tab to be 4 spaces. Let’s create a function that cycles
<code>tab-width</code> between 2, 4 and 8 spaces.</p>
<p>(I found the variable <code>tab-width</code> by using <code>apropos-variable</code> to search for
“tab”.)</p>
<div class='do'>
<div class='window default'>(<span class="keyword">defun</span> <span class="function-name">my-tab-width</span> ()
 <span class="doc">"Cycle tab-width between values 2, 4, and 8."</span>
 (interactive)
 (setq tab-width
 (<span class="keyword">cond</span> ((eq tab-width 8) 2)
 ((eq tab-width 2) 4)
 (t 8)))
 (redraw-display))
</div>
</div>
<p>The <code>cond</code> expression evaluates to 2 if <code>tab-width</code> equals 8; to 4 if
<code>tab-width</code> equals 2; and to 8 otherwise. Look up <code>cond</code> and <code>eq</code> in the Info
manuals if you like.</p>
<p>I’ve been naming all my functions “<em>my</em>-something” because elisp doesn’t have
separate namespaces for each mode or package; this way I can be sure my
functions won’t accidentally re-define an existing function that some editing
mode relies on.</p>
<p>Now let’s bind our new function to a key sequence, so we can invoke it
conveniently. <code><a class='glossary' href='glossary.html#keys'>C-c</a></code> followed by a letter is <a href="http://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html">reserved for users to define</a>,
so we’ll use <code><a class='glossary' href='glossary.html#keys'>C-c t</a></code>:</p>
<div class='do'>
<div class='window default'>(global-set-key (kbd <span class="string">"C-c t"</span>) 'my-tab-width)

</div>
</div>
<p>The meaning of “global” in <code>global-set-key</code> should be obvious. If you’d like a
keybinding just for <code>cc-mode</code>, use <code>define-key</code> to add the binding to the
mode’s keymap:</p>
<div class='window default'>(define-key c-mode-base-map (kbd <span class="string">"C-c t"</span>) 'my-tab-width)
</div>
<p>I discovered <code>c-mode-base-map</code> with <code><a class='glossary' href='glossary.html#keys'>C-h v c-mode- TAB TAB</a></code>. There is also a
<code>c-mode-map</code> which is just for the C language, rather than all languages
supported by <code>cc-mode</code>.</p>
<h2 id='auto-mode'>Associating file extensions with an <a class='glossary' href='glossary.html#majormode'>editing mode</a></h2>
<p>Say you want <code>.h</code> files to open in <code>c++-mode</code> rather than <code>c-mode</code>:</p>
<div class='do'>
<p><code><a class='glossary' href='glossary.html#keys'>C-h v auto-mode-alist</a></code></p>
<p><code><a class='glossary' href='glossary.html#keys'>C-h f add-to-list</a></code></p>
</div>
<div class='figure'>
<div class='window default'>(add-to-list 'auto-mode-alist
 '(<span class="string">"\\.h$"</span> . c++-mode))</div>
<div class='modeline'>-U:--- <b>*scratch*</b> All L6 (Lisp Interaction)----------------------------------------</div>
<div class='echoarea'><p><span class="prompt">Regexp I-search:</span> \.h$</p></div>
</div>
<p>The trickiest part will be getting the regular expression right—elisp doesn’t
have syntax for a regexp literal, so you have to put it inside a string, and
then the string backslash-escaping makes the regexp rather awful. See
<a href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Regexps.html">“Regexps”</a> in the
Emacs manual.</p>
<h2 id='homework'>Homework</h2>
<p>If you have a spare 30 minutes read Steve Yegge’s <a href="http://steve-yegge.blogspot.com/2008/01/emergency-elisp.html">Emergency Elisp</a>.</p>
<p>If you have a spare 6 months work through <a href="http://mitpress.mit.edu/sicp/">Structure and Interpretation of
Computer Programs</a>, a famous textbook from MIT
that teaches important (and some quite advanced) programming concepts and
techniques using a simple dialect of Lisp called Scheme. If you like “mathy”
things like the <a href="http://en.wikipedia.org/wiki/Sieve_of_Eratosthenes">Sieve of Eratosthenes</a> for finding prime numbers,
<a href="http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method">Heron’s method</a>
for calculating square roots, or estimating the value of pi using <a href="http://en.wikipedia.org/wiki/Monte_Carlo_method">Monte Carlo
simulation</a>, then you’ll love
this book.</p>
<p>If you had a collection of <code>.emacs</code> customizations collected from the web
before you started this guide to Emacs, go over them now and try to understand
them thoroughly.</p>
<p>In future, when you need a particular customization try to find the solution
from the manuals or the elisp sources before reaching for Google.</p>
<p>Don’t try to modify the elisp files that are part of the Emacs distribution.
For one, it won’t be easy to merge your changes when you update Emacs to a
newer version. Second, the files are byte-compiled so you’d have to recompile
them. Third, even if you did it still wouldn’t help because the core elisp
functions are <a href="http://www.gnu.org/software/emacs/manual/html_node/elisp/Building-Emacs.html">built into the Emacs image</a>,
so you’d have to recompile the whole program. Instead, use the variables and
hooks provided for customization.</p>
<p>Don’t pay attention to the Emacs manual whenever it tells you to use the <a href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html">“Easy
customization”</a>
facility (in some help <a class='glossary' href='glossary.html#buffers'>buffers</a> it will say “you can customize this variable”).
It’s referring to a really awkward semi-graphical interface for setting Emacs
variables. Best to keep all your customizations in your own init file.</p>
<div id='footnotes'>
<p><a id='fn1' href='#fnref1' class='footnote'>[1]</a>:
Try this:<br/>
<code>lynx --dump http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html |</code><br/>
<code>sed '/^References/,$ d' | wc -w</code></p>
<p><a id='fn2' href='#fnref2' class='footnote'>[2]</a>:
I <em>am</em> joking. Lisp does have plenty of real problems.</p>
<p><a id='fn3' href='#fnref3' class='footnote'>[3]</a>:
Actually a “symbol”. Curiously, elisp functions and variables live in
separate namespaces, so you can define the variable <code>+</code>, set it to <code>2</code>, and
still use <code>+</code> as a function in nonsensical statements like <code>(+ 1 +)</code>. Try it:<br/>
<code>(setq + 2)</code><br/>
<code>(+ 1 +)</code></p>
<p><a id='fn4' href='#fnref4' class='footnote'>[4]</a>:
“Other” here only refers to languages supported by <code>cc-mode</code>, not <em>any</em> other
language.</p>
</div>
<!-- Contents -->
<p class='next'><a rel='next' href='customize_colors.html'>Next: Fix that awful color scheme</a></p>
</div>
</body>
</html>