-
Notifications
You must be signed in to change notification settings - Fork 35
/
emacs-lisp-tutorial.html
executable file
·605 lines (487 loc) · 28.7 KB
/
emacs-lisp-tutorial.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
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Learn Emacs Lisp while customizing Emacs</title>
<!-- 2015-10-19 Mon 13:38 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="generator" content="Org-mode" />
<link rel="stylesheet" type="text/css" href="./css/foundation.min.css"></link>
<link href='http://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'></link>
<link rel="stylesheet" type="text/css" href="./css/org-export.css"></link>
<link rel="stylesheet" type="text/css" href="./css/style.css"></link>
<link rel="stylesheet" type="text/css" href="./css/emacs-notes.css"></link>
<script src="./js/jquery.min.js"></script>
<script src="./js/emacs-notes.js"></script>
</head>
<body>
<div id="content">
<h1 class="title">Learn Emacs Lisp while customizing Emacs</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">Why learn Emacs Lisp?</a></li>
<li><a href="#sec-2">How to run Emacs Lisp code</a></li>
<li><a href="#sec-3">How to save your configuration</a></li>
<li><a href="#sec-4">How to load modes to change the way that Emacs behaves</a></li>
<li><a href="#sec-5">How to specify options when you're calling functions</a></li>
<li><a href="#sec-6">How to set simple variables</a></li>
<li><a href="#sec-7">How to set buffer-local variables</a></li>
<li><a href="#sec-8">How to set more complex variables</a></li>
<li><a href="#sec-9">How to load libraries</a></li>
<li><a href="#sec-10">How to add to lists</a></li>
<li><a href="#sec-11">How to add package archives - to be written</a></li>
<li><a href="#sec-12">How to add hooks - to be written</a></li>
<li><a href="#sec-13">How to set up your own keyboard shortcuts</a></li>
<li><a href="#sec-14">How to define your own functions - to be written</a></li>
<li><a href="#sec-15">How to prompt for information - to be written</a></li>
<li><a href="#sec-16">How to change existing functions with advice - to be written</a></li>
<li><a href="#sec-17">Acknowledgements</a></li>
</ul>
</div>
</div>
<p>
Work in progress. Questions/ideas? <a href="mailto:[email protected]">[email protected]</a>
</p>
<p>
Available at <a href="http://sach.ac/baby-steps-elisp">http://sach.ac/baby-steps-elisp</a> <br />
Github: <a href="https://github.com/sachac/emacs-notes">https://github.com/sachac/emacs-notes</a> . Patches welcome. =)
</p>
<p>
While I'm drafting this, you may want to check out the following resources:
</p>
<ul class="org-ul">
<li><a href="http://bzg.fr/learn-emacs-lisp-in-15-minutes.html">http://bzg.fr/learn-emacs-lisp-in-15-minutes.html</a>
</li>
<li><a href="http://toumorokoshi.github.io/emacs-from-scratch-part-3-extending-emacs-with-elisp.html">http://toumorokoshi.github.io/emacs-from-scratch-part-3-extending-emacs-with-elisp.html</a>
</li>
<li><a href="https://www.gnu.org/software/emacs/manual/html_mono/eintr.html">An Introduction to Programming in Emacs Lisp</a>: A bit abstract, but a good place to start. Read it even if you don't understand everything. Read it again. Refer to it frequently. Graduate to the <a href="http://www.gnu.org/software/emacs/manual/elisp.html">Emacs Lisp reference manual</a> when you're more comfortable (or if you need to look up details).
</li>
<li><a href="http://ergoemacs.org/emacs/elisp.html">http://ergoemacs.org/emacs/elisp.html</a>: Good collection of idioms and common uses.
</li>
<li><a href="http://joelmccracken.github.io/entries/emacs-lisp-for-hackers-part-1-lisp-essentials/">http://joelmccracken.github.io/entries/emacs-lisp-for-hackers-part-1-lisp-essentials/</a>: Starts with ielm, focuses on data structures; other parts?
</li>
<li><a href="http://cjohansen.no/an-introduction-to-elisp">http://cjohansen.no/an-introduction-to-elisp</a>: Focuses on Emacs Lisp as a way of extending Emacs, uses programming examples (test cases)
</li>
<li><a href="http://steve-yegge.blogspot.com/2008/01/emergency-elisp.html">http://steve-yegge.blogspot.com/2008/01/emergency-elisp.html</a>
</li>
</ul>
<p>
UPDATE: Go check out <a href="http://pages.sachachua.com/emacs-notes/how-to-read-emacs-lisp.html">http://pages.sachachua.com/emacs-notes/how-to-read-emacs-lisp.html</a> instead.
</p>
<p>
Previous draft follows below.
</p>
<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1">Why learn Emacs Lisp?</h2>
<div class="outline-text-2" id="text-1">
<p>
Emacs is amazingly customizable. If you want to tweak Emacs to support the way that you'd like to work, learning Emacs Lisp will definitely pay off. People have used Emacs Lisp to turn Emacs into a musical instrument, a TODO manager, a webserver, and all sorts of other things.
</p>
<p>
You don't need to be a programmer in order to learn and use Emacs Lisp. Even though you'll technically be programming in it, just think of it as configuring Emacs. This guide will start you off with simple customizations, and then you can go from there. In this guide, you'll be changing options much like you might change them through other applications' Options dialog. It's just that in Emacs, it's easier to do most things in text.
</p>
<p>
In addition to reading this guide, you may want to check out <a href="http://planet.emacsen.org">Planet Emacsen</a> and <a href="http://www.emacswiki.org">Emacs Wiki</a> for plenty of inspiration. Seeing what other people have done with Emacs can nudge you to explore more of the Emacs Lisp code that makes it possible.
</p>
<p>
I'm going to assume that you've already installed Emacs 24 or later and that you're familiar with basic editing. If you haven't gone through the tutorial yet, you can click on the tutorial link that appears when Emacs starts up, or you can use <code>Ctrl-h t</code> (<code>help-with-tutorial</code>). All right. Let's start!
</p>
</div>
</div>
<div id="outline-container-sec-2" class="outline-2">
<h2 id="sec-2">How to run Emacs Lisp code</h2>
<div class="outline-text-2" id="text-2">
<p>
The first thing you need to learn is how to run Emacs Lisp. By default, Emacs starts up with a <code>*scratch*</code> buffer that's in Emacs Lisp mode. You can use this to try out code temporarily without saving it to your config. Type or paste in the code that you want to try, then use <code>M-x eval-buffer</code> to evaluate all the code in that buffer.
</p>
<p>
If you want to run some of the code (but not all the code), you can select the region and then type <code>M-x eval-region</code>.
</p>
<p>
Emacs Lisp code is made up of expressions that are enclosed in sets of parentheses. To run just one expression, put your cursor right after the last parenthesis (but not on the parenthesis itself). Type <code>C-x C-e</code> (<code>eval-last-sexp</code>). You should see the results that expression.
</p>
<p>
Let's try that with some examples. Type or copy the following into your <code>*scratch*</code> buffer and use <code>M-x eval-buffer</code>. It should show "Hello world" in the echo area near the bottom of your Emacs frame.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(message <span style="font-style: italic;">"Hello world"</span>)
</pre>
</div>
<p>
Try <code>M-x eval-region</code> and <code>C-x C-e</code> (<code>eval-last-sexp</code>) as well.
</p>
<p>
There are a few other ways to quickly evaluate Emacs Lisp code. If you just want to quickly evaluate something, try <code>M-:</code> (<code>eval-expression</code>). <code>M-x ielm</code> opens an interactive buffer where you can type code and then press <code>RET</code> (Enter). When you're starting out, you'll probably want to be able to easily read and modify the code, so I suggest using <code>M-x eval-buffer</code>, <code>M-x eval-region</code>, or <code>C-x C-e</code> (<code>eval-last-sexp</code>) instead. If you've downloaded <code>emacs-lisp-tutorial.org</code> and are reading this in Emacs, you can evaluate code by putting your text cursor on the <code>#+begin_src emacs-lisp</code> line and typing <code>C-c C-c</code>. Make sure to re-evaluate it if you make any changes. Might be handy.
</p>
<p>
Since the <code>*scratch*</code> buffer is not automatically saved to a file, you may want to put your code into a file instead. You can create any file with the <code>.el</code> extension (ex: <code>test.el</code>) and Emacs will switch to Emacs Lisp mode when you open it.
</p>
</div>
</div>
<div id="outline-container-sec-3" class="outline-2">
<h2 id="sec-3">How to save your configuration</h2>
<div class="outline-text-2" id="text-3">
<p>
When you like something and you want to make it part of your configuration, open the file <code>~/.emacs.d/init.el</code>. If you started with an older version of Emacs and have a <code>~/.emacs</code> file instead, be sure to move its contents to <code>~/.emacs.d/init.el</code> and remove the <code>~/.emacs</code> file.
</p>
<p>
It's usually safe to add your new code to the bottom of the file. If your <code>init.el</code> already contains some code, make sure you add your new code after the last closing parenthesis. If you're changing things like <code>load-path</code>, you may want to put the code earlier in the file (before the library is loaded). Save your <code>init.el</code> and restart Emacs.
</p>
<p>
What if you added something to your <code>init.el</code> that caused an error when you started Emacs? Don't worry. You can find out which part caused the error with <code>emacs --debug-init</code>. You can also start Emacs without your configuration file by typing <code>emacs -q</code> at the command-line. Then you can open your <code>init.el</code>, remove the problematic line, and restart to see if that fixed it.
</p>
<p>
Okay, let's start writing Emacs Lisp!
</p>
</div>
</div>
<div id="outline-container-sec-4" class="outline-2">
<h2 id="sec-4">How to load modes to change the way that Emacs behaves</h2>
<div class="outline-text-2" id="text-4">
<p>
Emacs has "modes" that load different pieces of functionality. You've already seen how Emacs Lisp Mode (or <code>emacs-lisp-mode</code>, which is the actual name in Emacs Lisp) changes the color of code in the <code>*scratch*</code> buffer. Other modes affect how you use Emacs. Here's an example of a mode that you may find useful. It turns on completion for <code>M-x</code>.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(icomplete-mode)
</pre>
</div>
<p>
Put that in your <code>*scratch*</code> and use <code>M-x eval-buffer</code> to evaluate it. Now try <code>M-x</code> again, and start typing <code>eval-buffer</code>. As you type, Emacs will suggest possible completions. There are even more <a href="http://sachachua.com/blog/2014/03/emacs-basics-call-commands-name-m-x-tips-better-completion-using-ido-helm/">shortcuts for M-x</a>, but this is probably a good start for you.
</p>
<p>
Here are some other modes that might be helpful:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(column-number-mode)
(visual-line-mode)
(global-hl-line-mode)
</pre>
</div>
<p>
Try using <code>C-x C-e</code> (<code>eval-last-sexp</code>) to evaluate these lines one at a time. Put your cursor after the ending <code>)</code> on each line, then type <code>C-x C-e</code>.
</p>
<p>
<code>icomplete-mode</code> and the other modes are all examples of <b>functions</b>. The first "word" after the opening parenthesis of an Emacs Lisp expression is usually a function. You can learn more about functions with <code>F1 f</code> (<code>describe-function</code>). There are tons of functions in Emacs (and even more once you start installing and loading packages). You can discover useful functions by browsing through other people's configuration, looking at the source code of other functions you're interested in, checking out <a href="http://emacswiki.org">EmacsWiki</a>, asking on mailing lists and newsgroups, or using the <code>M-x apropos-command</code> function.
</p>
</div>
</div>
<div id="outline-container-sec-5" class="outline-2">
<h2 id="sec-5">How to specify options when you're calling functions</h2>
<div class="outline-text-2" id="text-5">
<p>
Some functions need more information. For example, <code>prefer-coding-system</code> is a useful function if you work with files that have special characters or different languages. The following Emacs Lisp code sets the default to UTF-8, which is a common standard.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(prefer-coding-system 'utf-8)
</pre>
</div>
<p>
Here's another example. Let's say that you want to open a file whenever you start Emacs. The function to open a file is called <code>find-file</code>, and you can give it the name of the file to open. The code below switches to a buffer visiting file "todo.org" in your home directory. If the buffer doesn't exist, it will be created. If the file doesn't exist, it will be created automatically when the buffer is saved - for example, when you press <code>C-x C-s</code> (<code>save-buffer</code>) in that buffer.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(find-file <span style="font-style: italic;">"~/todo.org"</span>)
</pre>
</div>
<p>
(See <i>A Baby Steps Guide to Managing Your Tasks with Org</i> for more info on Org files.)
</p>
<p>
Here's a third example, for when you get tired of typing "yes" or "no" to confirmation prompts:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(fset 'yes-or-no-p 'y-or-n-p)
</pre>
</div>
<p>
<code>fset</code> is a function that replaces a function (yes-or-no-p) with another function (y-or-n-p). Sounds complicated? A little. You can use the snippet right now without digging into how it works, and you'll learn more about functions over time.
</p>
</div>
</div>
<div id="outline-container-sec-6" class="outline-2">
<h2 id="sec-6">How to set simple variables</h2>
<div class="outline-text-2" id="text-6">
<p>
In addition to calling functions, you can also set values that affect what code does.
Many functions check the value of different <b>variables</b>. For example, this tells Emacs to keep old versions.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq delete-old-versions -1)
</pre>
</div>
<p>
<code>setq</code> means "Set this quoted variable to this value." The quoted part just means that the first argument (in this case, <code>delete-old-versions</code>) is treated as a variable name instead of being used to look up a <b>different</b> variable to set. The code is the same as the code below:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(set (quote delete-old-versions) -1)
</pre>
</div>
<p>
… but the <code>setq</code> version is shorter, so everyone uses that instead. This is also why you should be careful to type <code>setq</code> instead of <code>set</code>, as <code>set</code> refers to a different function. If you accidentally use <code>set</code> instead, you'll usually see something like a <code>Wrong type argument: symbolp</code>, <i>value</i>
</p>
<p>
To see the documentation for a variable, use <code>F1 v</code> (<code>describe-variable</code>) and type in the variable name. The variable name is the first argument to <code>setq</code>, so you would type in <code>F1 f delete-old-versions</code>.
</p>
<p>
You can customize many variables through the <code>M-x customize</code> interface, but you'll most often see people sharing their configuration with Emacs Lisp code instead. It can be shorter to say "Add this code to your init.el" than it is to say "Use <code>M-x customize-variable</code> to change the <code>user-email-address</code> value", especially if there are lots of options to change. Not everything can be changed through the Customize interface, too. Emacs Lisp is more powerful, and it's easier to read afterwards. I tend to use <code>M-x customize</code> to explore, but I use Emacs Lisp code to set things up.
</p>
<p>
Like the way there are tons of functions, there are also tons of variables, and you can discover interesting variables using the same techniques: reading other people's code, exploring, etc.
</p>
</div>
</div>
<div id="outline-container-sec-7" class="outline-2">
<h2 id="sec-7">How to set buffer-local variables</h2>
<div class="outline-text-2" id="text-7">
<p>
Some variables are <b>buffer-local</b>. This means that the value in one buffer (or file) is separate from the values in other buffers. To find out if a variable is local to a buffer, use <code>F1 v</code> (<code>describe-variable</code>) to look at the documentation for that variable. For example, the documentation for <code>tab-width</code> has "Automatically becomes buffer-local when set".
</p>
<p>
You can set the default value of a buffer-local variable with <code>setq-default</code>. The following code sets the tab width to 2 by default:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq-default tab-width 2)
</pre>
</div>
</div>
</div>
<div id="outline-container-sec-8" class="outline-2">
<h2 id="sec-8">How to set more complex variables</h2>
<div class="outline-text-2" id="text-8">
<p>
Some variables contain lists of data. Here's an example:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq backup-directory-alist '((<span style="font-style: italic;">"."</span> . <span style="font-style: italic;">"~/.emacs.d/backups"</span>)))
</pre>
</div>
<p>
This is one of the things people usually want to change right away. By default, Emacs saves backup files in the current directory. These are the files ending in <code>~</code> that are cluttering up your directory lists. This code stashes them in <code>~/.emacs.d/backups</code>, where you can find them with <code>C-x C-f</code> (<code>find-file</code>) when you need to.
</p>
<p>
<code>alist</code> stands for <b>association list</b>. Each entry in the list is
enclosed in (…). The first part of the list is the key that is used
to look it up, like the way a dictionary has words. The second part of
the list is the value that Emacs uses, like the definitions in a dictionary.
If you're curious, the <a href="http://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html">Emacs Lisp reference manual</a> has more details.
</p>
</div>
</div>
<div id="outline-container-sec-9" class="outline-2">
<h2 id="sec-9">How to load libraries</h2>
<div class="outline-text-2" id="text-9">
<p>
Emacs has a lot of libraries. To save memory and to simplify operation, not all of them are loaded at startup. In addition to the libraries that are built into Emacs, you can also download packages and Emacs Lisp files, save them to a directory that Emacs can find, and load them.
</p>
<p>
Here is one way to load the code from an Emacs Lisp file.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(load-file <span style="font-style: italic;">"~/.emacs.secrets"</span>)
</pre>
</div>
<p>
If the file doesn't exist, you'll get an error. You can check if it exists with:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="font-weight: bold;">if</span> (file-exists-p <span style="font-style: italic;">"~/.emacs.secrets"</span>)
(load-file <span style="font-style: italic;">"~/.emacs.secrets"</span>))
</pre>
</div>
<p>
If you use your Emacs configuration on multiple systems, you might want to load some configuration based on the name of the system you're on. For example:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="font-weight: bold;">if</span> (file-exists-p (concat <span style="font-style: italic;">"~/.emacs.d/"</span> (system-name) <span style="font-style: italic;">".el"</span>))
(load-file (concat <span style="font-style: italic;">"~/.emacs.d/"</span> (system-name) <span style="font-style: italic;">".el"</span>)))
</pre>
</div>
<p>
To find out which file the code is looking for, you can put your point <b>after</b> the closing <code>)</code> for in <code>.el")</code> (so it's on the second parentheses) and then type <code>C-x C-e</code> (<code>eval-last-sexp</code>). That will display the result of the expression in your echo area.
</p>
<p>
<code>load-file</code> loads a specified file if you know its path. For libraries, though, it's easier to use <code>require</code>. Here's an example that loads the <code>eldoc</code> library and turns on the mode. Eldoc displays information about Emacs Lisp functions or variables in the minibuffer when you move your point.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">eldoc</span>)
(eldoc-mode)
</pre>
</div>
<p>
<code>require</code> takes the name of the feature to load. Here, it's ='eldoc=. the quotation mark before it means that it should be treated as a literal symbol, not as a variable to look at for a value. If this features has already been loaded, <code>require</code> does nothing. If not, <code>require</code> searches through the list of directories in <code>load-path</code> for an Emacs Lisp file with that name and which provides that feature.
</p>
<p>
If you've downloaded the Emacs Lisp file or package on your own, though, you'll want to add its directory to the load path. See <a href="#sec-10">How to add to lists</a> for details.
</p>
</div>
</div>
<div id="outline-container-sec-10" class="outline-2">
<h2 id="sec-10">How to add to lists</h2>
<div class="outline-text-2" id="text-10">
<p>
<code>add-to-list</code> is a straightforward way to add an item to a list. Here's an example of adding something to <code>load-path</code>, which controls where Emacs looks for packages or features to load:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(add-to-list 'load-path <span style="font-style: italic;">"~/elisp"</span>)
</pre>
</div>
<p>
If you want to add to the end of the list, you can specify <code>t</code> as the optional APPEND argument, which is the third argument in the list.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(add-to-list 'load-path <span style="font-style: italic;">"~/elisp/sample-mode"</span> t)
</pre>
</div>
<p>
<code>add-to-list</code> adds an item only if it doesn't already exist. The list must already be defined. If you try to add an item to a list that does not exist yet, you'll get the following error: <code>Symbol's value as variable is void:</code> <i>listname</i>. Make sure you load the feature before you add to any lists defined in that feature.
</p>
<p>
If you want to always add something to the beginning of the list, you can delete it from the list and then add it back.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq load-path (delete <span style="font-style: italic;">"~/elisp"</span> load-path))
(add-to-list 'load-path <span style="font-style: italic;">"~/elisp"</span>))
</pre>
</div>
<p>
If you don't mind duplicates (or you want them), you can use <code>cons</code> instead. <code>cons</code> constructs a <b>cons cell</b>, which is the data structure that makes up lists. For more information about cons, see the Emacs Lisp Intro section on <a href="http://www.gnu.org/software/emacs/manual/html_node/eintr/car-cdr-_0026-cons.html">car, cdr, cons: Fundamental Functions</a>.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq load-path (cons <span style="font-style: italic;">"~/elisp"</span> load-path))
</pre>
</div>
</div>
</div>
<div id="outline-container-sec-11" class="outline-2">
<h2 id="sec-11">How to add package archives - to be written</h2>
</div>
<div id="outline-container-sec-12" class="outline-2">
<h2 id="sec-12">How to add hooks - to be written</h2>
</div>
<div id="outline-container-sec-13" class="outline-2">
<h2 id="sec-13">How to set up your own keyboard shortcuts</h2>
<div class="outline-text-2" id="text-13">
<p>
If you find that you regularly need to run one or more commands
that don't have a default key binding set up for them, it's time to
start defining your own key bindings.
</p>
<p>
Each key binding you define belongs to a specific <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Keymaps.html">keymap</a>.
</p>
<p>
If you want a binding to be available globally, irrespective of the
mode you are in, you can add it to the <code>global-map</code> like this:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"M-s r b"</span>) 'revert-buffer)
</pre>
</div>
<p>
Here, we are creating a global key binding (<code>M-s r b</code>) for the
<code>revert-buffer</code> function.
</p>
<p>
You can also override an existing key binding this way. For
instance, the function <code>list-buffers</code> (which brings up a list of
all buffers that are currently open) is bound to <code>C-x C-b</code> by
default. If you prefer <code>ibuffer</code> for listing and operating on open
buffers but have already built up muscle memory for the <code>C-x C-b</code>
binding, you can rebind it like this:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"C-x C-b"</span>) 'ibuffer)
</pre>
</div>
<p>
You can also set up keybindings to work only in <i>specific</i> modes.
This is done with the help of the <code>define-key</code> function:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(define-key org-mode-map (kbd <span style="font-style: italic;">"C-c a"</span>) 'org-agenda)
</pre>
</div>
<p>
Here, we are telling Emacs to create a key binding for the
<code>org-agenda</code> command that will only work in <code>org-mode</code> buffers.
</p>
<p>
It is important to note that mode-specific key bindings will
override global bindings. So unless you are explicitly trying to
override an existing binding (as described above), before setting
up a new binding it is always a good idea to check if the key
sequence you are thinking of is already bound to a command. (This
can sometimes be a great way of discovering functionality you
hadn't been aware of!) To check whether a binding is currently in
use <i>in any of the modes that are enabled for the current buffer</i>,
type <code>C-h k</code> (<code>describe-key</code>) followed by the binding. If it isn't,
you will see a message in the echo area telling you that the
binding <code>is undefined</code>. If it <i>is</i> bound to a command, Emacs will
bring up a <code>*Help*</code> window with documentation for the command.
</p>
<p>
It can sometimes be desirable to <i>unset</i> specific key bindings. For
global bindings, you can use the <code>global-unset-key</code> function:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-unset-key (kbd <span style="font-style: italic;">"M-g M-g"</span>))
</pre>
</div>
<p>
Mode-specific bindings can be disabled by setting them to <code>nil</code>:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(define-key magit-mode-map (kbd <span style="font-style: italic;">"M-s"</span>) nil)
</pre>
</div>
<p>
If you define lots of custom keybindings, you may want to check out
John Wiegley's <code>bind-key</code> package. If you install <code>bind-key</code> and
use it to define keybindings, you can then use <code>M-x describe-personal-keybindings</code> to see which keybindings
Here are some examples for <code>bind-key</code>:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp"> (<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">bind-key</span>)
(bind-key <span style="font-style: italic;">"C-c a"</span> 'org-agenda)
(bind-key <span style="font-style: italic;">"C-+"</span> 'text-scale-increase)
(bind-key <span style="font-style: italic;">"C--"</span> 'text-scale-decrease)
<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">You can use bind-key to modify keymaps</span>
(bind-key <span style="font-style: italic;">"i"</span> 'org-agenda-clock-in org-agenda-mode-map)
</pre>
</div>
</div>
</div>
<div id="outline-container-sec-14" class="outline-2">
<h2 id="sec-14">How to define your own functions - to be written</h2>
</div>
<div id="outline-container-sec-15" class="outline-2">
<h2 id="sec-15">How to prompt for information - to be written</h2>
</div>
<div id="outline-container-sec-16" class="outline-2">
<h2 id="sec-16">How to change existing functions with advice - to be written</h2>
<div class="outline-text-2" id="text-16">
<p>
(c) 2014 Sacha Chua - Creative Commons Attribution License (feel free to use, share, remix)
</p>
</div>
</div>
<div id="outline-container-sec-17" class="outline-2">
<h2 id="sec-17">Acknowledgements</h2>
<div class="outline-text-2" id="text-17">
<p>
Thanks to:
</p>
<ul class="org-ul">
<li>itsjeyd for the section on keyboard shortcuts
</li>
</ul>
</div>
</div>
</div>
<div id="postamble" class="status">
<div class="back-to-top"><a href="#top">Back to top</a> | <a href="mailto:[email protected]">E-mail me</a></div>
</div>
</body>
</html>