-
Notifications
You must be signed in to change notification settings - Fork 35
/
how-to-read-emacs-lisp.html
executable file
·2152 lines (1755 loc) · 102 KB
/
how-to-read-emacs-lisp.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
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?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>
<!-- 2015-11-16 Mon 15:51 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Read Lisp, Tweak Emacs: How to read Emacs Lisp so that you can customize Emacs</title>
<meta name="generator" content="Org-mode" />
<meta name="author" content="Sacha Chua" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
pre.src-sh:before { content: 'sh'; }
pre.src-bash:before { content: 'sh'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-R:before { content: 'R'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-java:before { content: 'Java'; }
pre.src-sql:before { content: 'SQL'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
/*]]>*/-->
</style>
<link rel="stylesheet" type="text/css"
href="http://sachachua.com/blog/wp-content/themes/sacha-v3/foundation/css/foundation.min.css"></link>
<link rel="stylesheet" type="text/css" href="http://sachachua.com/org-export.css"></link>
<link rel="stylesheet" type="text/css" href="http://sachachua.com/blog/wp-content/themes/sacha-v3/style.css"></link>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2013 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
</head>
<body>
<div id="preamble" class="status">
<a name="top" id="top"></a>
</div>
<div id="content">
<h1 class="title">Read Lisp, Tweak Emacs: How to read Emacs Lisp so that you can customize Emacs</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orgheadline1">Introduction</a></li>
<li><a href="#orgheadline2">The wonderful world of Emacs customization</a>
<ul>
<li><a href="#orgheadline3">"Why do I have to learn Emacs Lisp in order to get Emacs to do what I want? Shouldn't Emacs just come with reasonable defaults?"</a></li>
<li><a href="#orgheadline4">"If I customize my Emacs, I'll have a hard time working with other people or on other computers."</a></li>
<li><a href="#orgheadline5">"I don't have the time to fiddle around with this."</a></li>
</ul>
</li>
<li><a href="#orgheadline6">"How can I try Emacs Lisp code?"</a>
<ul>
<li><a href="#orgheadline7">Finding Emacs Lisp code</a>
<ul>
<li><a href="#orgheadline8">Emacs documentation</a></li>
<li><a href="#orgheadline9">Packages</a></li>
<li><a href="#orgheadline10">Webpages, blog posts, and the Emacs Wiki</a></li>
<li><a href="#orgheadline11">Mailing lists, newsgroups, and Q&A sites</a></li>
</ul>
</li>
<li><a href="#orgheadline12">Trying out code</a>
<ul>
<li><a href="#orgheadline13">M-x ielm (Inferior Emacs Lisp Mode)</a></li>
<li><a href="#orgheadline14">The <code>*scratch*</code> buffer and Emacs Lisp <code>.el</code> files</a></li>
<li><a href="#orgheadline15">M-: (eval-expression)</a></li>
<li><a href="#orgheadline16">C-x C-e (eval-last-sexp)</a></li>
<li><a href="#orgheadline17">If you want that code to run every time you start Emacs…</a></li>
<li><a href="#orgheadline18">Practice</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#orgheadline19">"How can I understand what Emacs Lisp code does?"</a>
<ul>
<li><a href="#orgheadline20">Learn more about functions</a></li>
<li><a href="#orgheadline21">Learn more about variables</a></li>
<li><a href="#quoting">Understand symbols</a></li>
<li><a href="#orgheadline23">Work with lists</a>
<ul>
<li><a href="#load-path">Add to a list</a></li>
<li><a href="#orgheadline25">Hooks</a></li>
<li><a href="#orgheadline26">Deleting from a list</a></li>
<li><a href="#package-archives">Dot notation</a></li>
</ul>
</li>
<li><a href="#orgheadline28">Review</a></li>
</ul>
</li>
<li><a href="#orgheadline29">"How can I customize Emacs to make things more convenient?"</a>
<ul>
<li><a href="#orgheadline30">Keyboard shortcuts</a>
<ul>
<li><a href="#orgheadline31">Setting keybindings in all buffers</a></li>
<li><a href="#orgheadline32">What does <code>kbd</code> do? How can I figure out which key it sets?</a></li>
<li><a href="#orgheadline33">Multi-key shortcuts</a></li>
<li><a href="#orgheadline34">Binding keys to other keys</a></li>
<li><a href="#orgheadline35">Dealing with errors: "Key sequence <span class="underline">__</span> starts with non-prefix key <span class="underline">_</span>"</a></li>
<li><a href="#modekeys">Setting keybindings in a particular mode</a></li>
<li><a href="#orgheadline37">Other ways people bind keys</a></li>
</ul>
</li>
<li><a href="#orgheadline38">Defuns - function definitions</a></li>
<li><a href="#orgheadline39">Lambdas - anonymous functions</a></li>
</ul>
</li>
<li><a href="#orgheadline40">"How can I add more features and deal with errors?"</a>
<ul>
<li><a href="#load">Adding more features to Emacs</a>
<ul>
<li><a href="#installing-packages">Installing packages</a></li>
<li><a href="#unpackaged">Other Emacs Lisp files</a></li>
</ul>
</li>
<li><a href="#errors">"Oh no! I have an error!"</a>
<ul>
<li><a href="#orgheadline44">Scan error: "Unbalanced parentheses" or "Containing expression ends prematurely"</a></li>
<li><a href="#orgheadline45">Cannot open load file: …</a></li>
<li><a href="#void-function">Lisp error: (void-function …)</a></li>
<li><a href="#void-variable">Symbol's value as variable is void: <span class="underline">_</span></a></li>
<li><a href="#orgheadline48">I'm using C-x C-e (eval-last-sexp) and I don't get the results I expected</a></li>
</ul>
</li>
<li><a href="#orgheadline50">Wrapping up the beginner course</a></li>
</ul>
</li>
<li><a href="#orgheadline51">Author's notes</a></li>
</ul>
</div>
</div>
<p>
<a id="orgtarget1"></a>
</p>
<div id="outline-container-orgheadline1" class="outline-2">
<h2 id="orgheadline1">Introduction</h2>
<div class="outline-text-2" id="text-orgheadline1">
<p>
Hi! This is a guide to help you pick up the basics of reading
customization code for Emacs - little snippets of Emacs Lisp that you
can add to your <code>~/.emacs.d/init.el</code> to change how Emacs works. I hope
this will help you learn how to borrow interesting snippets from
README files and other people's configs so that you can tweak Emacs to
fit the way you work. This is not a detailed guide on how to
understand Emacs internals, but by the time you find yourself digging
through comint.el to figure out what's going on with command
interpretation, you probably already know your way around.
</p>
<p>
We'll assume that you already have Emacs installed and that you've
gone through the built-in tutorial (<b>Help - Emacs Tutorial</b>, <code><f1> t</code>,
<code>C-h t</code>, or <code>M-x help-with-tutorial</code>). If you haven't upgraded to at
least Emacs 24.x, please do - it's worth it! I'll also assume you have
a little programming background or can deal with the concepts of
variables and functions. Feel free to ask questions if you get stuck
on something or if you want to clarify your understanding.
</p>
<p>
Please e-mail questions, comments, and suggestions to
<a href="mailto:[email protected]">[email protected]</a>. I want to make this guide better, and I'd love to
hear from you. If you would like to help improve this guide, you can
find it on <a href="https://github.com/sachac/emacs-notes/blob/gh-pages/how-to-read-emacs-lisp.org">Github</a> - pull requests welcome. This guide is dual-licensed
under the Creative Commons Attribution License and the GNU Free
Documentation License, so feel free to read, share, and build on it.
</p>
<p>
You can find this guide on the Web at
<a href="http://emacslife.com/how-to-read-emacs-lisp.html">http://emacslife.com/how-to-read-emacs-lisp.html</a> . If you want an EPUB
version or a downloadable HTML version, you can get it from <a href="https://gumroad.com/l/xkzAI">Gumroad</a>
(free/pay-what-you-want).
</p>
<div class="CONVENTIONS">
<p>
Some conventions we'll use:
</p>
<ul class="org-ul">
<li>Inline code will be <code>boxed and monospace</code> in the HTML version and generally surrounded by <code>equal signs</code> in plain text.</li>
<li><p>
Code samples will be monospace and in boxes in the HTML version, and enclosed in <code>#+begin_src</code> … <code>#+end_src</code> in plain text. Example:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(message <span class="org-string">"Hello world"</span>)
</pre>
</div></li>
</ul>
</div>
<p>
Now, on with the guide.
</p>
</div>
</div>
<div id="outline-container-orgheadline2" class="outline-2">
<h2 id="orgheadline2">The wonderful world of Emacs customization</h2>
<div class="outline-text-2" id="text-orgheadline2">
<p>
To make the most of Emacs, learn how to read and write Emacs Lisp.
Most of Emacs is written in Emacs Lisp: the packages that add extra
functionality, the configuration code to set different options. You
can change large parts of how Emacs behaves even without restarting
Emacs.
</p>
<p>
Remember: with great power comes lots of time debugging if you mess
things up. This is a guide to help you avoid messing up, so you can
build the confidence to learn more. It's worth it. Start with one-line
in ten years (or three, or twenty, or next month - all up to you),
you'll be able to tweak Emacs to do more things than other people
might imagine a text editor can do.
</p>
<p>
This is what Emacs Lisp code looks like:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(message <span class="org-string">"Hello world!"</span>)
</pre>
</div>
<p>
Or something slightly more useful:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq delete-old-versions -1)
</pre>
</div>
<p>
If you want to start playing around with Emacs Lisp code right away, jump ahead to the section on <a href="#orgtarget2">"How can I try Emacs Lisp code?"</a>.
</p>
</div>
<div id="outline-container-orgheadline3" class="outline-3">
<h3 id="orgheadline3">"Why do I have to learn Emacs Lisp in order to get Emacs to do what I want? Shouldn't Emacs just come with reasonable defaults?"</h3>
<div class="outline-text-3" id="text-orgheadline3">
<p>
Reasonable defaults make sense for specific people. Other people might
have completely different ideas for how they want a tool to work.
Many people use Emacs and have (occasionally quite strong)
opinions about how they want it to work. It's difficult to change the defaults for everyone<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>, and since Emacs is so customizable, people tend to just fix things for themselves. If you learn how to read and write Emacs Lisp, you can pick up tips from other people's configurations and ask people for help.
</p>
<p>
There are some initiatives to put together common settings or "starter
kits" that people may like. You can check them out for inspiration or
use them as a starting point. Here are a few popular ones:
</p>
<ul class="org-ul">
<li><a href="https://github.com/bbatsov/prelude">https://github.com/bbatsov/prelude</a></li>
<li><a href="https://github.com/technomancy/better-defaults">https://github.com/technomancy/better-defaults</a></li>
</ul>
<p>
You can read them to pick up ideas for customizing Emacs, or you can
use them as a starting point for your own configuration. Note that
starter kits change the behaviour of Emacs from what you might expect
based on manuals and webpages. If you've added configuration code that
you don't understand, be sure to mention it when asking for help,
since people might otherwise assume you're starting with the defaults.
It may be a good idea to look at starter kits and other people's
configuration for inspiration, but add snippets slowly instead of
copying things wholesale.
</p>
</div>
</div>
<div id="outline-container-orgheadline4" class="outline-3">
<h3 id="orgheadline4">"If I customize my Emacs, I'll have a hard time working with other people or on other computers."</h3>
<div class="outline-text-3" id="text-orgheadline4">
<p>
I find that optimizing my Emacs configuration for my happiness is
worth the mild annoyance of not having my shortcuts handy (or worse,
not having Emacs!) when I pair-program with other people. If you're
pair-programming with other people, you can switch your configuration
or use a different editor. <code>emacs -q</code> starts Emacs without your
personal configuration. It's good to be familiar with other editors
like Vi so that you can be productive even if that's all you have, and
then learn how to make the most of Emacs so that you can reap the
benefits over the decades.
</p>
<p>
Many people synchronize their configuration across multiple computers
by using version control systems like Git or file synchronization
tools like Dropbox. You can set up Emacs to check for hostname or
other system variables before loading system-specific configuration.
</p>
<p>
You might think it's not worth customizing Emacs if you spend most of
your time ssh-ed into other servers. With Emacs, you can use <a href="http://www.gnu.org/software/tramp/">TRAMP</a> to
edit files through SSH and sudo in your local Emacs.
</p>
</div>
</div>
<div id="outline-container-orgheadline5" class="outline-3">
<h3 id="orgheadline5">"I don't have the time to fiddle around with this."</h3>
<div class="outline-text-3" id="text-orgheadline5">
<p>
Emacs Lisp code can help you save time by automating repetitive
actions, smoothening rough edges, or enabling time-saving features
like autocompletion. Investing some time can help you save a lot of
time later. Learning from other Emacs users can help you figure out
customizations that take little time for big results.
</p>
<p>
That said, it's a good idea to take a step back and figure out if what
you're trying to customize is really worth it. One of the occupational
hazards of using Emacs is that tweaking your Emacs configuration can
be fun, almost addictive. If you catch yourself spending four hours
fiddling with something minor, it might be time to put that aside and
focus on getting stuff done first.<sup><a id="fnr.2" class="footref" href="#fn.2">2</a></sup>
</p>
</div>
</div>
</div>
<div id="outline-container-orgheadline6" class="outline-2">
<h2 id="orgheadline6">"How can I try Emacs Lisp code?"</h2>
<div class="outline-text-2" id="text-orgheadline6">
<p>
<a id="orgtarget2"></a>
</p>
<div class="OBJECTIVES">
<p>
After this section, you should be able to
</p>
<ul class="org-ul">
<li>find Emacs Lisp code to study and use</li>
<li>try Emacs Lisp code before saving it to your configuration (that way, you don't have to keep restarting Emacs)</li>
<li>add code to your configuration so that it runs whenever Emacs starts</li>
</ul>
</div>
</div>
<div id="outline-container-orgheadline7" class="outline-3">
<h3 id="orgheadline7">Finding Emacs Lisp code</h3>
<div class="outline-text-3" id="text-orgheadline7">
<p>
It's easier to learn how to read Emacs Lisp when you start with simple examples that will help you use Emacs more effectively. Here are some useful sources:
</p>
</div>
<div id="outline-container-orgheadline8" class="outline-4">
<h4 id="orgheadline8">Emacs documentation</h4>
<div class="outline-text-4" id="text-orgheadline8">
<p>
Manuals and FAQs for Emacs-related tools often include code snippets. For example, the <a href="https://www.gnu.org/software/emacs/manual/efaq.html">Emacs FAQ</a> has an entry like this:
</p>
<pre class="example">
5.47 How can I tell Emacs to fill paragraphs with a single space after each period?
===================================================================================
Add the following line to your `.emacs' file:
(setq sentence-end-double-space nil)
</pre>
<p>
You can read the Emacs manual by typing <code>C-h i</code> (<code>info</code>) and choosing the <b>Emacs</b> item. If you're on a terminal that doesn't understand the <code>C-h</code> key, use <code>F1</code> or <code>M-x help</code> whenever you see a reference to <code>C-h</code>, or use <code>M-x</code> to call the command by name (ex: <code>F1 i</code>, or <code>M-x info</code>). To jump directly to the Emacs manual, you can use <code>C-h r</code> (<code>info-emacs-manual</code>). You can also find the Emacs Manual at <a href="http://www.gnu.org/software/emacs/manual/emacs.html">http://www.gnu.org/software/emacs/manual/emacs.html</a> .
</p>
</div>
</div>
<div id="outline-container-orgheadline9" class="outline-4">
<h4 id="orgheadline9">Packages</h4>
<div class="outline-text-4" id="text-orgheadline9">
<p>
Emacs has lots of packages in different repositories, many of which require a little extra code in order to be used to full effect. You can use <code>M-x package-list-packages</code> to list the packages that Emacs knows about by default. You will need an Internet connection for that.
</p>
<p>
If you're new to Emacs, try getting used to Emacs without packages first. There's plenty of functionality already built in. When you come across a gap, chances are that someone has written a package to make Emacs behave the way you want it to. Since there are lots of packages that do similar things, you might want to look for recommendations or ask people which ones you should start with.
</p>
<p>
In addition to the default package repository, there are other community-supported repositories. See <a href="http://emacslife.com/how-to-read-emacs-lisp.html#installing-packages">Installing packages</a> if you would like to install a package from a different repository.
</p>
<p>
If you install a package, check out the README, description, documentation, or source code comments for interesting packages to find suggested code to add to your Emacs configuration.
</p>
<p>
Here are some packages that might be interesting:
</p>
<ul class="org-ul">
<li>company: adds text completion</li>
<li>yasnippet: snippets and templates</li>
<li>undo-tree: visualize your undo/redo history</li>
</ul>
<p>
You will need to be connected to the Internet in order to view and install packages. You can use <code>M-x package-list-packages</code> to show the available packages and read the descriptions for the packages above.
</p>
</div>
</div>
<div id="outline-container-orgheadline10" class="outline-4">
<h4 id="orgheadline10">Webpages, blog posts, and the Emacs Wiki</h4>
<div class="outline-text-4" id="text-orgheadline10">
<p>
While searching for information related to Emacs, you'll probably come across lots of Emacs Lisp snippets. The <a href="http://www.emacswiki.org/">EmacsWiki</a> has lots of code, too. Since this is a community-maintained wiki, you may come across code that is out of date or that refers to packages that you don't have. I've included common errors in this guide to help you figure things out - see <a href="http://emacslife.com/how-to-read-emacs-lisp.html#errors">"Oh no! I have an error!"</a>
</p>
<p>
Here are some sites you may want to check out:
</p>
<ul class="org-ul">
<li>EmacsWiki: CategoryDotEmacs - <a href="http://www.emacswiki.org/emacs/CategoryDotEmacs">http://www.emacswiki.org/emacs/CategoryDotEmacs</a></li>
<li>Emacs Redux - <a href="http://emacsredux.com/">http://emacsredux.com/</a></li>
<li>What the Emacs.d?! - <a href="http://whattheemacsd.com/">http://whattheemacsd.com/</a></li>
<li>The very unofficial .emacs home - <a href="http://www.dotemacs.de/localfiles.html">http://www.dotemacs.de/localfiles.html</a></li>
</ul>
</div>
</div>
<div id="outline-container-orgheadline11" class="outline-4">
<h4 id="orgheadline11">Mailing lists, newsgroups, and Q&A sites</h4>
<div class="outline-text-4" id="text-orgheadline11">
<p>
There are many places where you can ask for help with Emacs. gnu.emacs.help is available as a <a href="https://lists.gnu.org/mailman/listinfo/help-gnu-emacs">mailing list</a> or as a newsgroup - check your favourite Usenet server or use <a href="http://dir.gmane.org/gmane.emacs.help">Gmane</a>. <a href="http://stackoverflow.com/questions/tagged/emacs">StackOverflow</a> and <a href="http://www.quora.com/Emacs">Quora</a> are popular as well. If you ask questions there, you might get answers in the form of Emacs Lisp code. You'll also come across Emacs Lisp code while searching for answers.
</p>
<p>
Find a snippet of Emacs Lisp code you want to understand more deeply, or look at the examples in the sections below.
</p>
</div>
</div>
</div>
<div id="outline-container-orgheadline12" class="outline-3">
<h3 id="orgheadline12">Trying out code</h3>
<div class="outline-text-3" id="text-orgheadline12">
<p>
It's easier to understand code if you can experiment with it. Emacs Lisp code is made up of <b>symbolic expressions</b> (known as S-expressions, expressions, or sexp for short). Expressions are usually enclosed in pairs of parentheses. There are several ways you can try Emacs Lisp expressions before saving them in your configuration.
</p>
<p>
Note: As you experiment with Emacs Lisp, you might run into errors. Check out <a href="http://emacslife.com/how-to-read-emacs-lisp.html#errors">"Oh no! I have an error!"</a> for some common errors and what to do about them.
</p>
<p>
Here are some ways you can run Emacs Lisp code. I'll explain them in more detail below.
</p>
<ul class="org-ul">
<li><code>M-x ielm</code> (Inferior Emacs Lisp Mode) - evaluates expressions after you press <code>RET</code>, which is handy for pasting in code</li>
<li>The <code>*scratch*</code> buffer and Emacs Lisp files - makes it easy to edit and re-evaluate expressions</li>
<li><code>M-:</code> (<code>eval-expression</code>) - good for quickly evaluating Emacs Lisp code while you're doing something else</li>
<li><code>C-x C-e</code> (<code>eval-last-sexp</code>) - handy when reading expressions in manuals or other text</li>
</ul>
</div>
<div id="outline-container-orgheadline13" class="outline-4">
<h4 id="orgheadline13">M-x ielm (Inferior Emacs Lisp Mode)</h4>
<div class="outline-text-4" id="text-orgheadline13">
<p>
The Inferior Emacs Lisp Mode gives you a prompt where you can type or paste in Emacs Lisp code. Start it with <code>M-x ielm</code>. Press <code>RET</code> after you enter code, and the results will be displayed. "Inferior" is a technical term referring to how it's run, not a comment on the simplicity of the tool or the code you want to try. You can go to previously-executed code, change things, and press <code>RET</code> to run (or "evaluate") it again.
</p>
<p>
If you're copying or typing code, make sure your parentheses are all matched - every "<code>(</code>" should have a "<code>)</code>". IELM won't run the code unless it sees the closing parenthesis. So the following code is incomplete:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(message <span class="org-string">"Hello</span>
</pre>
</div>
<p>
but this will work:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(message <span class="org-string">"Hello world"</span>)
</pre>
</div>
<p>
You can use <code>M-p</code> (<code>comint-previous-input</code>) to go through the previously-typed expressions. <code>M-n</code> (<code>comint-next-input</code>) goes forward.
</p>
<p>
Tip: When you're trying out an unfamiliar mode, use <code>C-h m</code> (<code>describe-mode</code>) to learn more about the commands that are available in that mode.
</p>
</div>
</div>
<div id="outline-container-orgheadline14" class="outline-4">
<h4 id="orgheadline14">The <code>*scratch*</code> buffer and Emacs Lisp <code>.el</code> files</h4>
<div class="outline-text-4" id="text-orgheadline14">
<p>
When Emacs starts, it creates a buffer called <code>*scratch*</code> with the following contents:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp"><span class="org-comment-delimiter">;; </span><span class="org-comment">This buffer is for notes you don't want to save, and for Lisp evaluation.</span>
<span class="org-comment-delimiter">;; </span><span class="org-comment">If you want to create a file, visit that file with C-x C-f,</span>
<span class="org-comment-delimiter">;; </span><span class="org-comment">then enter the text in that file's own buffer.</span>
</pre>
</div>
<p>
You can add code to the end.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp"><span class="org-comment-delimiter">;; </span><span class="org-comment">This buffer is for notes you don't want to save, and for Lisp evaluation.</span>
<span class="org-comment-delimiter">;; </span><span class="org-comment">If you want to create a file, visit that file with C-x C-f,</span>
<span class="org-comment-delimiter">;; </span><span class="org-comment">then enter the text in that file's own buffer.</span>
(message <span class="org-string">"Hello world"</span>)
</pre>
</div>
<p>
Note: <code>;</code> is the comment character. Anything after the comment character is considered part of the comment. Make sure you add your code on a new line, not in the comment. <code>;;</code> above is how we usually start comments that take up the entire line.
</p>
<p>
To run code ("evaluate" it, in Emacs terms), you can use the following commands based on what you want to run:
</p>
<ul class="org-ul">
<li><code>M-x eval-buffer</code> runs all the code in the current file or buffer.</li>
<li><code>M-x eval-region</code> runs the code in the selected region. You can select a region of text by using the mouse. Alternatively, you can type <code>C-SPC</code> to mark the start of the region, then move your cursor to the end of the region. If you want to learn more about selecting regions, check out the Emacs tutorial (<code>C-h t</code>, <code>C-h t</code>, or <code>M-x help-with-tutorial</code>).</li>
<li><code>C-x C-e</code> (<code>eval-last-sexp</code>) runs the expression (S-expression, or sexp) before the cursor. NOTE: Your cursor should be after the closing parenthesis, not on it.</li>
</ul>
<p>
In the <code>*scratch*</code> buffer, you can also press <code>C-j</code> (<code>eval-print-last-sexp</code>) after an expression in order to evaluate it and display the results in the buffer.
</p>
<p>
The <code>*scratch*</code> buffer is not automatically saved. If you would like to save your code for future use, you can create a file with an <code>.el</code> ending. <code>el</code> stands for Emacs Lisp, and Emacs will open these files in Emacs Lisp mode. The commands listed above work in Emacs Lisp files.
</p>
</div>
</div>
<div id="outline-container-orgheadline15" class="outline-4">
<h4 id="orgheadline15">M-: (eval-expression)</h4>
<div class="outline-text-4" id="text-orgheadline15">
<p>
If you want to quickly try a single expression, you can use <code>M-:</code> (<code>eval-expression</code>). It will display the results in the echo area near the bottom of your screen. If you want to insert the results into your buffer, call it with <code>C-u M-:</code> instead. For example, you can use <code>C-u M-: (* 18 2)</code> to multiply 18 and 2 quickly. To review previous results, you can switch to the <code>*Messages*</code> buffer.
</p>
</div>
</div>
<div id="outline-container-orgheadline16" class="outline-4">
<h4 id="orgheadline16">C-x C-e (eval-last-sexp)</h4>
<div class="outline-text-4" id="text-orgheadline16">
<p>
<code>C-x C-e</code> (<code>eval-last-sexp</code>) runs the expression (S-expression, or sexp) before the cursor. NOTE: Your cursor should be after the closing parenthesis, not on it. <code>C-x C-e</code> (<code>eval-last-sexp</code>) works in lots of buffers, not just in Emacs Lisp ones. You can use it to quickly try expressions while reading manual pages or other documentation.
</p>
<p>
You can get the text file for this lesson from <a href="http://emacslife.com/read-lisp-tweak-emacs/beginner-1-try-emacs-lisp.txt">http://emacslife.com/read-lisp-tweak-emacs/beginner-1-try-emacs-lisp.txt</a> . If you're reading this lesson in Emacs, try putting your cursor after the closing <code>)</code> and calling <code>C-x C-e</code> (<code>eval-last-sexp</code>) on the following line:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(menu-bar-mode -1)
</pre>
</div>
<p>
This turns off the menu bar along the top of your Emacs window. If you like the menu bar, you can turn it on again by evaluating:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(menu-bar-mode 1)
</pre>
</div>
<p>
As with <code>M-:</code> (<code>eval-expression</code>), you can use the <code>C-u</code> prefix to insert the results instead of displaying them. For example, try using <code>C-u C-x C-e</code> (<code>eval-last-sexp</code>) to evaluate the following expression:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(* 6 7)
</pre>
</div>
</div>
</div>
<div id="outline-container-orgheadline17" class="outline-4">
<h4 id="orgheadline17">If you want that code to run every time you start Emacs…</h4>
<div class="outline-text-4" id="text-orgheadline17">
<p>
… <b>then</b> add it to your <code>~/.emacs.d/init.el</code> file. You can generally add new code at the end. If the code has something to do with <code>load-path</code>, it might be good to add it to the beginning instead. That way, your <code>load-path</code> changes can take effect before any libraries are loaded.
</p>
<p>
Note: The Emacs configuration file used to be <code>~/.emacs</code>, and most webpages refer to that. <code>~/.emacs</code> still works - in fact, if you have that, it may stop Emacs from loading <code>~/.emacs.d/init.el</code>. On the other hand, if you use <code>~/.emacs.d/init.el</code> (and move your <code>~/.emacs</code> code to that file instead), then you have one less hidden file in your home directory (<code>~</code>). If you're adding code to your config and it's not getting loaded, make sure you have either <code>~/.emacs</code> or <code>~/.emacs.d/init.el</code>, but not both.
</p>
<p>
When you're starting out, it's a good idea to keep your configuration in one file. Later on, you can split it up into multiple files if you want.
</p>
</div>
</div>
<div id="outline-container-orgheadline18" class="outline-4">
<h4 id="orgheadline18">Practice</h4>
<div class="outline-text-4" id="text-orgheadline18">
<p>
Try this out:
</p>
<div class="PRACTICE">
<ol class="org-ol">
<li>Browse through <a href="http://www.emacswiki.org/emacs/CategoryDotEmacs">http://www.emacswiki.org/emacs/CategoryDotEmacs</a> for some code that looks like it will make Emacs work more like the way you want it to. If you need help figuring it out, send me a copy of the code ([email protected]).</li>
<li><p>
Use <code>M-x ielm</code> to evaluate this expression interactively:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">system-type
</pre>
</div>
<p>
This shows you the value of the <code>system-type</code> variable. Note: Variables can be evaluated without the parentheses, but functions can't. Use You can use <code>ielm</code> to call functions like this, though:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(max 2 6 10 5)
</pre>
</div></li>
<li><p>
Use <code>M-:</code> (<code>eval-expression</code>) buffer to evaluate the following expression:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(* 21 2)
</pre>
</div>
<p>
<code>M-:</code> is handy for quick calculations. Remember, you can use it with
<code>C-u</code> (that is, <code>C-u M-:</code>) to <b>insert</b> the result into the buffer.
Try it now: <code>C-u M-: (* 21 2)</code>
</p></li>
<li><p>
Use <code>C-x C-e</code> (<code>eval-last-sexp</code>) to evaluate the expression below. If you are reading this in Emacs, you can evaluate it by putting your cursor after the last <code>)</code> and calling <code>C-x C-e</code> (<code>eval-last-sexp</code>). If you are reading this outside Emacs, you can copy that text into any buffer and then use <code>C-x C-e</code> (<code>eval-last-sexp</code>) to evaluate it.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(* (+ 1 2) 3)
</pre>
</div></li>
<li>Add <code>(message "Hello, world!")</code> to the end of your <code>~/.emacs.d/init.el</code> (or <code>~/.emacs</code>, if you're using that file instead). Use <code>M-x eval-buffer</code> to load your config. It should display the message near the bottom of your screen. If you restart Emacs, you should also see that message briefly.</li>
<li>Call <code>M-x visual-line-mode</code> to tell Emacs to visually wrap lines without actually changing the text. If you like this, add <code>(add-hook 'text-mode-hook 'turn-on-visual-line-mode)</code> to your <code>~/.emacs.d/init.el</code>.</li>
</ol>
</div>
</div>
</div>
</div>
</div>
<div id="outline-container-orgheadline19" class="outline-2">
<h2 id="orgheadline19">"How can I understand what Emacs Lisp code does?"</h2>
<div class="outline-text-2" id="text-orgheadline19">
<p>
<a id="orgtarget3"></a>
</p>
<div class="OBJECTIVES">
<p>
After this module, you should be able to
</p>
<ul class="org-ul">
<li>learn more about the functions and variables that you find in Emacs Lisp code</li>
<li>pay attention to important details when copying code, such as ' (quote) and . (dot notation)</li>
<li>add to and remove items from lists</li>
</ul>
</div>
</div>
<div id="outline-container-orgheadline20" class="outline-3">
<h3 id="orgheadline20">Learn more about functions</h3>
<div class="outline-text-3" id="text-orgheadline20">
<p>
The symbol after <code>(</code> is usually a function name, unless it's part of a list of literals (numbers, strings, etc.). You'll learn how to recognize literal lists later.
</p>
<p>
In math, operators like + and * go between the numbers they will work on. In Emacs Lisp, the operator (or the "function") is at the start of the expression, followed by the things it's going to operate on ("arguments").
</p>
<p>
Here's how to calculate (1 + 2) * 3 in Emacs Lisp. Note that the multiplication is surrounded by parentheses, even if we usually leave out the parentheses in math. That's because in Emacs Lisp, all function calls have their own set of parentheses.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(* (+ 1 2) 3)
</pre>
</div>
<p>
Let's take a closer look:
</p>
<pre class="example">
( ( 1 + 2 ) * 3 ) Math expression
( * ( + 1 2 ) 3 ) Emacs Lisp expression
</pre>
<div class="figure">
<p><img src="http://emacslife.com/images/math-to-emacs-lisp.png" alt="math-to-emacs-lisp.png" />
</p>
</div>
<p>
See how the operators are at the beginning of whatever they're working on, and the parentheses enclose everything that's related to that operator?
</p>
<p>
Understanding this will let you read code like:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-hl-line-mode)
</pre>
</div>
<p>
This calls the <code>global-hl-line-mode</code> function, which highlights the current line.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(show-paren-mode)
</pre>
</div>
<p>
This calls the <code>show-paren-mode</code> function, which shows matching parentheses when your cursor is after them.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(blink-cursor-mode -1)
</pre>
</div>
<p>
This calls the <code>blink-cursor-mode</code> function with <code>-1</code> as the argument, which turns blinking cursors off.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(find-file <span class="org-string">"~/todo.org"</span>)
</pre>
</div>
<p>
This calls the <code>find-file</code> function with the <code>todo.org</code> file in your home directory. The code above switches to a buffer visiting the file "todo.org" in your home directory (<code>~</code>). 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">(turn-on-eldoc-mode)
</pre>
</div>
<p>
This turns on <code>eldoc-mode</code>, which displays the argument list for the current function. You can move your cursor around to see argument lists for other functions.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(add-hook 'emacs-lisp-mode-hook 'turn-on-eldoc-mode)
</pre>
</div>
<p>
This turns on <code>eldoc-mode</code> when a buffer is switched to Emacs Lisp mode. You'll learn more about why some things have <code>'</code> and some don't in the section "Some things are taken literally" in this module.
</p>
<p>
To find out if something is a function, what it does, what arguments it takes, and if it has any keyboard shortcuts, use the <code>C-h f</code> (<code>describe-function</code>) command. Give it the function name. For example, <code>C-h f add-hook</code> will show you the documentation for <code>add-hook</code>, and <code>C-h f show-paren-mode</code> will show you the documentation for that.
</p>
<p>
The documentation for <code>show-paren-mode</code> starts with "show-paren-mode is an interactive autoloaded Lisp function". Interactive functions are functions that can be called with <code>M-x</code> or with keyboard shortcuts, and they're usually functions that you'll find useful while interacting with Emacs. Non-interactive functions tend to be for internal use, such as code that other Emacs Lisp code will call. Read the description of the function to learn more about arguments that you can pass to change its behavior. If it mentions a prefix argument, that means that you can change its behaviour by typing <code>C-u</code> before you call the function.
</p>
<p>
Emacs is extensively documented. Whenever you come across a strange function, check it out with <code>C-h f</code> (<code>describe-function</code>). If you have the Emacs Lisp sources installed, you can learn more about how the functions work. Just follow the link from the documentation, or use <code>M-x find-function</code> to learn more.
</p>
<p>
In fact, you can learn more about functions even if you don't know what they're called. For example, if you know the keyboard shortcut or you can see the item on one of the menus, use <code>C-h k</code> (<code>describe-key</code>) to learn more about that command. Emacs will show you the function that's associated with that keyboard shortcut or menu item. You can also look up functions by keyword if you use <code>M-x apropos</code>.
</p>
<div class="PRACTICE">
<ol class="org-ol">
<li>Use <code>C-h f</code> (<code>describe-function</code>) to learn more about the following functions:</li>
<li><code>describe-function</code>: Yes, this is also a function! The documentation will give you alternative keyboard shortcuts such as <code>F1 f</code>.</li>
<li><code>find-file</code>: You can use this to open specific files. See the function description to learn how to use this with remote files.</li>
<li><code>message</code>: This is an example of a function that has a variable number of arguments. The first argument says how the message will be displayed, and the rest of the arguments contain the values.</li>
<li><code>just-one-space</code>: Handy way to clean up space. What keyboard shortcut is it bound to?</li>
<li><p>
Look for Emacs configuration code that you would like to understand further. Use <code>C-h f</code> (<code>describe-function</code>) to learn more about the functions in the code. For example, here are some snippets from my configuration. What do the functions do?
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(savehist-mode 1)
(tooltip-mode -1)
(tool-bar-mode -1)
(menu-bar-mode -1)
(scroll-bar-mode -1)
(prefer-coding-system 'utf-8)
</pre>
</div></li>
</ol>
</div>
</div>
</div>
<div id="outline-container-orgheadline21" class="outline-3">
<h3 id="orgheadline21">Learn more about variables</h3>
<div class="outline-text-3" id="text-orgheadline21">
<p>
Variables are containers that can hold different values. In Emacs Lisp, you can change the value of a variable as many times as you want, and you can change it to different types of data as needed.
</p>
<p>
Like the way you can use <code>C-h f</code> (<code>describe-function</code>) to learn more about a function, you can use <code>C-h v</code> (<code>describe-variable</code>) to learn more about a variable by name. For example, use <code>C-h v</code> to look up the documentation for <code>visible-bell</code>. It says:
</p>
<pre class="example">
Non-nil means try to flash the frame to represent a bell.
</pre>
<p>
A non-nil value is anything that isn't <code>nil</code>, such as <code>t</code> or <code>1</code>. If you would like to configure your Emacs to flash instead of ringing the bell,
you could add the following code to your <code>~/.emacs.d/init.el</code>:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(setq visible-bell t)
</pre>
</div>
<p>
Here's another useful snippet:
</p>