├── README.md └── README.org /README.md: -------------------------------------------------------------------------------- 1 | # Emacs Lisp Guide 2 | 3 | ### Table of Contents 4 | 5 | - [Emacs Lisp Guide](#emacs-lisp-guide) 6 | - [Table of Contents](#table-of-contents) 7 | - [Audience](#audience) 8 | - [Programming in Emacs Lisp](#programming-in-emacs-lisp) 9 | - [After reading this guide](#after-reading-this-guide) 10 | - [Trivial basics](#trivial-basics) 11 | - [Evaluation](#evaluation) 12 | - [Discoverability](#discoverability) 13 | - [Finding functions of keybindings](#finding-functions-of-keybindings) 14 | - [Getting documentation](#getting-documentation) 15 | - [Find all bindings in the current buffer](#find-all-bindings-in-the-current-buffer) 16 | - [Searching for documentation topics](#searching-for-documentation-topics) 17 | - [Jumping to definition](#jumping-to-definition) 18 | - [Describe functions](#describe-functions) 19 | - [Basic concepts](#basic-concepts) 20 | - [Buffers](#buffers) 21 | - [Buffer-local variables](#buffer-local-variables) 22 | - [Project-wide buffer-local variables](#project-wide-buffer-local-variables) 23 | - [The point](#the-point) 24 | - [The region](#the-region) 25 | - [Text properties](#text-properties) 26 | - [Debugging](#debugging) 27 | - [Editing](#editing) 28 | - [Paredit](#paredit) 29 | - [Navigating](#navigating) 30 | - [Killing](#killing) 31 | - [Raising](#raising) 32 | - [Wrapping](#wrapping) 33 | - [Splitting](#splitting) 34 | - [Manipulating the buffer](#manipulating-the-buffer) 35 | - [Text properties](#text-properties-1) 36 | - [Navigating the buffer](#navigating-the-buffer) 37 | - [Save excursion](#save-excursion) 38 | - [Querying the buffer](#querying-the-buffer) 39 | - [Temporary buffers](#temporary-buffers) 40 | - [Defining interactive functions](#defining-interactive-functions) 41 | - [Defining your own major mode](#defining-your-own-major-mode) 42 | - [Defining a minor mode](#defining-a-minor-mode) 43 | - [Markers](#markers) 44 | - [Overlays](#overlays) 45 | - [Standard practices](#standard-practices) 46 | - [Namespacing](#namespacing) 47 | - [Alternative sources](#alternative-sources) 48 | 49 | ## Audience 50 | 51 | Programmers who are too busy to read through long tutorials and 52 | manuals, but who want to extend their editor. You don't need to learn 53 | everything from the ground up, just enough knowledge to be 54 | self-sufficient. You've been using Emacs for a while and now it's time 55 | you started making some handy extensions for yourself. 56 | 57 | There are a bunch of existing guides, but they don't strike the right 58 | balance of useful and helpful. Some just list functions, others try to 59 | explain Emacs Lisp from the ground up as a language. You don't need to 60 | know everything right away. See the [Alternative sources](#alternative-sources) 61 | section for a list of these. 62 | 63 | ## Programming in Emacs Lisp 64 | 65 | I'm not going to explain the Emacs Lisp language itself in any 66 | detail. Programming in 67 | [Emacs Lisp](http://en.wikipedia.org/wiki/Emacs_Lisp) (look at the 68 | Wikipedia page for the academic details) is similar to programming in 69 | Python, Scheme, Common Lisp, JavaScript, Ruby, and languages like 70 | that. Its syntax is funny but otherwise it's an imperative language 71 | with similar data structures. 72 | 73 | ***One important difference*** compared to usual languages to be aware 74 | of is that it has _dynamic scope_ by default. See 75 | [Dynamic Binding](https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Binding.html#Dynamic-Binding) 76 | in the manual for the details. Almost all Emacs Lisp code you come 77 | across today will be using 78 | this. [Lexical Binding](https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html#Lexical-Binding) 79 | has recently been added to Emacs, it will take a while for this to 80 | permeate. 81 | 82 | Like all Lisps, Emacs Lisp has macros which you can [read about in the 83 | manual at your leisure.](https://www.gnu.org/software/emacs/manual/html_node/elisp/Macros.html#Macros) 84 | 85 | ## After reading this guide 86 | 87 | The best, most comprehensive resource on Emacs Lisp is 88 | [the manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html). I 89 | will reference this manual throughout this guide. I will not repeat 90 | what's already there. You can reference this manually in a random 91 | access fashion when you need to solve a problem. 92 | 93 | I reference the manual throughout the guide by HTML link, but you can 94 | read it inside your Emacs itself. Run: `C-h i m Elisp RET` 95 | 96 | ## Trivial basics 97 | 98 | These are the basics to syntax that you can lookup in any guide or 99 | just by looking at some Emacs Lisp code. I am assuming you're a 100 | programmer who can pick things up like this just by looking at code. I 101 | include these because I use them later: 102 | 103 | ``` lisp 104 | (* 2 3) 105 | (concat "a" "b") 106 | (defun func (arg1 arg2) 107 | "Always document your functions." 108 | ) 109 | (defvar var-name 110 | "Always document your variables.") 111 | (let ((x 1) 112 | (y 2)) 113 | ...) 114 | ``` 115 | 116 | In Lisp the normal `LET` doesn't let you refer to previous variables, 117 | so you need to use `LET*` for that. This is likely to trip people up, 118 | so I include it here. 119 | 120 | ``` lisp 121 | (let* ((x 1) 122 | (y x)) 123 | ...) 124 | ``` 125 | 126 | To do many things at once in one expression, use `PROGN`: 127 | 128 | ``` lisp 129 | (progn do-this 130 | do-that) 131 | ``` 132 | 133 | [See manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Local-Variables.html#Local-Variables) 134 | for details. 135 | 136 | The way to set variables is not obvious: 137 | 138 | ``` lisp 139 | (setq var-name value) 140 | ``` 141 | 142 | Equality and comparison operators: 143 | 144 | * `(eq major-mode 'a)` 145 | * `(= 0 1)` 146 | * `(> 0 1)` 147 | * `(string= "a" "b")` 148 | * `(string> "a" "b")` 149 | 150 | Emacs Lisp has a bunch of equality operators. See 151 | [the manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Equality-Predicates.html) 152 | for gory details. 153 | 154 | Data structures available: lists, vectors, rings, hashtables. Look them up in 155 | [the manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html). 156 | 157 | ## Evaluation 158 | 159 | * Use `M-:` to evaluate any Emacs Lisp expression and print the 160 | result. I personally use this constantly. 161 | * Use `C-x C-e` to evaluate the previous s-expression in the 162 | buffer. I personally never use this. See next binding. 163 | * Use `C-M-x` to evaluate the current top-level s-expression. I use 164 | this to re-apply `defvar` and `defun` declarations. 165 | * There is a REPL available by `M-x ielm`. I tend to use `M-:` rather 166 | than the REPL but you might like it. 167 | * Use `M-x eval-buffer` to evaluate the whole buffer of Emacs Lisp 168 | code. 169 | 170 | ## Discoverability 171 | 172 | A very important thing as an Emacs Lisp programmer is being able to 173 | get the information you want in a few keystrokes. Here's a list of 174 | ways to find what you need when you're writing Elisp code. 175 | 176 | ### Finding functions of keybindings 177 | 178 | Find the function called by a keybinding: `C-h k` 179 | 180 | This will show something like: 181 | 182 | C-p runs the command previous-line, which is an interactive compiled 183 | Lisp function in `simple.el'. 184 | 185 | It is bound to C-p. 186 | 187 | (previous-line &optional ARG TRY-VSCROLL) 188 | 189 | You can click the link `simple.el` to go directly to the definition of 190 | that function. Very handy indeed. 191 | 192 | ### Getting documentation 193 | 194 | Functions and variables are distinguished in Emacs Lisp, so there are 195 | two commands to do lookups: 196 | 197 | * Run `C-h f` to show documentation for a function. This also works 198 | for macros. 199 | * Run `C-h v` to show documentation for a variable. 200 | 201 | You'll see something like: 202 | 203 | mapcar is a built-in function in `C source code'. 204 | 205 | (mapcar FUNCTION SEQUENCE) 206 | 207 | Apply FUNCTION to each element of SEQUENCE, and make a list of the results. 208 | The result is a list just as long as SEQUENCE. 209 | SEQUENCE may be a list, a vector, a bool-vector, or a string. 210 | 211 | ### Find all bindings in the current buffer 212 | 213 | Run `C-h b` to show a massive list of keybindings and the command they 214 | run. You'll see something like, e.g. in `markdown-mode`: 215 | 216 | C-c C-x d markdown-move-down 217 | C-c C-x l markdown-promote 218 | C-c C-x m markdown-insert-list-item 219 | 220 | ### Searching for documentation topics 221 | 222 | Use the commands called `apropos`. 223 | 224 | * `M-x apropos` 225 | * `M-x apropos-command` 226 | * `M-x apropos-library` 227 | * `M-x apropos-documentation` 228 | 229 | ### Jumping to definition 230 | 231 | Install this package: 232 | [elisp-slime-nav](https://github.com/purcell/elisp-slime-nav) 233 | 234 | Now you can use `M-.` to jump to the identifer at point and `M-,` to 235 | jump back. 236 | 237 | ### Describe functions 238 | 239 | The range of `M-x describe-` functions are useful: 240 | 241 | * `M-x describe-mode` (aka `C-h m`) 242 | * `M-x describe-face` 243 | 244 | Other ones have been mentioned above as keybindings. 245 | 246 | ## Basic concepts 247 | 248 | ### Buffers 249 | 250 | All Emacs Lisp code when run has a current buffer. Operations that 251 | claim to work on "the buffer" work on this current buffer. Some handy 252 | functions, which you can run `C-h f` on to get more info: 253 | 254 | * `(current-buffer)` - get the current buffer. 255 | * `(with-current-buffer buffer-or-name ...)` - temporarily use the given buffer. 256 | * `(set-buffer buffer-or-name)` - set the current buffer without 257 | switching to it. 258 | * `(switch-to-buffer name)` - switch to the buffer visually. 259 | 260 | See 261 | [Buffers](https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffers.html#Buffers) 262 | in the manual for detailed info. 263 | 264 | ### Buffer-local variables 265 | 266 | Buffers have local variables, for example: 267 | 268 | * major-mode 269 | 270 | You can use this variable to see what mode you're in, if you need it. 271 | 272 | If you want to set your own buffer-local variable, use this: 273 | 274 | ``` lisp 275 | (defvar your-variable-name nil "Your documentation here.") 276 | ``` 277 | 278 | Then later on in your code that will run in a given buffer, use: 279 | 280 | ``` lisp 281 | (set (make-local-variable 'your-variable-name) ) 282 | ``` 283 | 284 | This is very handy in many scenarios when writing functionality. Note 285 | that buffer local variables are reset when you revert the buffer or 286 | change modes. 287 | 288 | See 289 | [manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer_002dLocal-Variables.html#Buffer_002dLocal-Variables) 290 | for details. 291 | 292 | ### Project-wide buffer-local variables 293 | 294 | A handy way to set a buffer local variable for every file that's 295 | within a directory structure is to use 296 | [a `.dir-locals.el` file.](https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html) 297 | 298 | ``` lisp 299 | ((nil . ((indent-tabs-mode . t) 300 | (fill-column . 80))) 301 | (c-mode . ((c-file-style . "BSD") 302 | (subdirs . nil))) 303 | ("src/imported" 304 | . ((nil . ((change-log-default-name 305 | . "ChangeLog.local")))))) 306 | ``` 307 | 308 | ### The point 309 | 310 | All Emacs Lisp code has a current point in the current buffer. It's a 311 | number. It refers to where the cursor is. See 312 | [the manual entry for point](http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html), 313 | but here's the basics: 314 | 315 | * `(point)` - current point 316 | * `(point-max)` - maximum point of the buffer 317 | * `(point-min)` - minimum point of the buffer (why is this not just `0`? 318 | Because of 319 | [narrowing](http://www.gnu.org/software/emacs/manual/html_node/elisp/Narrowing.html#Narrowing)). 320 | 321 | ### The region 322 | 323 | Sometimes the region can be active, and you can use it in your Emacs 324 | Lisp code to manipulate text specially. See 325 | [the manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/The-Region.html#The-Region) 326 | for details. Rundown: 327 | 328 | * `(region-beginning)` - beginning of the region (a point) 329 | * `(region-end)` - end of the region (a point) 330 | * `(use-region-p)` - whether to try to use region-beginning/region-end 331 | for manipulation. Handy for use in commands. 332 | * `(region-active-p)` - also handy to know whether the region is 333 | active. 334 | 335 | Here's an command that uses some region functions: 336 | 337 | ``` lisp 338 | (defun print-upper-region () 339 | "Demo to print the uppercased version of the active region." 340 | (interactive) 341 | (when (region-active-p) 342 | (message "%S" (let ((string (buffer-substring (region-beginning) 343 | (region-end)))) 344 | (with-temp-buffer 345 | (insert string) 346 | (upcase-region (point-min) 347 | (point-max)) 348 | (buffer-substring-no-properties (point-min) 349 | (point-max))))))) 350 | ``` 351 | 352 | To run it, `C-M-x` it, select some text and run `M-x print-upper-region`. 353 | 354 | ### Text properties 355 | 356 | When you manipulate text in Elisp, it can have properties applied to 357 | it, and those properties can be queried. Full details are 358 | [here](http://www.gnu.org/software/emacs/manual/html_node/elisp/Text-Properties.html#Text-Properties) 359 | but see the "Manipulating the buffer" section in this guide for examples. 360 | 361 | ## Debugging 362 | 363 | Run `M-: (setq debug-on-error t) RET` and any errors will open up the 364 | debugger. 365 | 366 | I'll write more about using the debugger stepper and breakpoints later. 367 | 368 | ## Editing 369 | 370 | ### Paredit 371 | 372 | Install and enable 373 | [paredit](http://www.emacswiki.org/emacs/ParEdit). Nobody sane writes 374 | Lisp without paredit (or its shiny cousin, 375 | [smartparens](https://github.com/Fuco1/smartparens); 376 | or its evil twin, 377 | [lispy](https://github.com/abo-abo/lispy)). You will never 378 | have unbalanced parentheses, brackets, braces, or strings. Learn to 379 | accept this and you will enjoy this mode. 380 | 381 | As discussed in the discoverability section, use `C-h f paredit-mode 382 | RET` to see the documentation for this mode. 383 | 384 | Learn the following helpful keybindings: 385 | 386 | #### Navigating 387 | 388 | * `C-M-u` - Go up a node. 389 | * `)` - Go to the end of the node or the end of the parent node when repeated. 390 | * `C-M-f` - Go to the end of the node. 391 | * `C-M-b` - Go to the start of the node. 392 | 393 | #### Killing 394 | 395 | `C-k` - Kill everything from here to the end of the line, including 396 | any following lines that are included in the scope of the nodes 397 | being killed. It will also kill inside strings but stop at the end 398 | of the string. 399 | 400 | #### Raising 401 | 402 | `M-r` - Replace the parent node by the current node. 403 | 404 | (|foo) -> foo 405 | (foo |bar mu) -> bar 406 | (foo (bar |mu zot) bob) -> (foo mu bob) 407 | 408 | #### Wrapping 409 | 410 | * `C-M-(` to wrap the following node in parens. 411 | * Alternatively, `C-M-SPC` to select the whole node, or just use your 412 | normal region selection and run `(` or 413 | `[` or `{` to wrap that selection. 414 | 415 | #### Splitting 416 | 417 | * `M-s` to split the current node. This works on parenthesized expressions or strings. 418 | * `M-J` to join two nodes. Works same as above in reverse. 419 | 420 | ## Manipulating the buffer 421 | 422 | These are the most common: 423 | 424 | * `(insert "foo" "bar")` - to insert text at point. 425 | * `(delete-region start end)` - to delete the region of text. 426 | * `(insert-buffer-substring-no-properties buffer start end)` - insert text from another buffer. 427 | * `(insert-file-contents )` - insert from a file. 428 | 429 | Any other command that inserts things can be called from Emacs Lisp, too. 430 | 431 | ### Text properties 432 | 433 | To add properties to text in the buffer, use: 434 | 435 | ``` lisp 436 | (put-text-property start end 'my-property-name ) 437 | ``` 438 | 439 | To completely reset the properties of text to just this, use: 440 | 441 | ``` lisp 442 | (set-text-properties start end 'my-property-name ) 443 | ``` 444 | 445 | To retrieve properties back from the text, use: 446 | 447 | ``` lisp 448 | (get-text-property 'my-property-name) 449 | ``` 450 | 451 | To propertize a string before it's inserted into a buffer, use: 452 | 453 | ``` lisp 454 | (propertize "hello" 'my-property-name 'another-prop ) 455 | ``` 456 | 457 | ## Navigating the buffer 458 | 459 | Here are the common ones: 460 | 461 | * `(goto-char )` - go to the point. 462 | * `(forward-char n)` - go forward n chars. Accepts a negative argument. 463 | * `(end-of-line)` - self-explanatory. 464 | * `(beginning-of-line)` - self-explanatory. 465 | * `(skip-chars-forward "chars")` - skip given chars. 466 | * `(skip-chars-backward "chars")` - skip given chars back. 467 | * `(search-forward "foo")` - search for foo, move cursor there. 468 | * `(search-backward "foo")` - search backward. 469 | * `(search-forward-regexp "blah")` - same, but with regexes. 470 | * `(search-backward-regexp "blah")` - same, but with regexes. 471 | 472 | If there's a kind of navigation you want to do that you don't know the function name for, think of how you would do it with your keyboard and then use `C-h k` on the commands to find out the functions being run. 473 | 474 | ### Save excursion 475 | 476 | Often you want to jump around the buffer to either query or manipulate something, and then go back to where you were originally. To do this, use: 477 | 478 | ``` lisp 479 | (save-excursion ...) 480 | ``` 481 | 482 | For example: 483 | 484 | ``` lisp 485 | (save-excursion (beginning-of-line) (looking-at "X")) 486 | ``` 487 | 488 | Will return whether the current line starts with `X`. 489 | 490 | Similarly there is `save-window-excursion`. 491 | 492 | ## Querying the buffer 493 | 494 | * `(buffer-substring start end)` - get the string at point, including text properties. 495 | * `(buffer-substring-no-properties start end)` - get the string at point, excluding text properties. 496 | * `(buffer-string)` - return the string of the whole buffer. 497 | * `(looking-at "[a-zA-Z]+")` - does text following point match the regex? 498 | * `(looking-back "[a-zA-Z]+")` - does text preceding point match the regex? 499 | 500 | ## Temporary buffers 501 | 502 | It's often useful to do some work in a temporary buffer so that you 503 | can use your normal Elisp code to generate a string and some 504 | properties, for example: 505 | 506 | ``` lisp 507 | (with-temp-buffer 508 | (insert "Hello!")) 509 | ``` 510 | 511 | ## Defining interactive functions 512 | 513 | To be able to run a function of your own from a keybinding, it needs 514 | to be interactive. You need to add `(interactive)` to your `defun`: 515 | 516 | ``` lisp 517 | (defun foo () 518 | "Some function." 519 | (interactive) 520 | (do-some-stuff)) 521 | ``` 522 | 523 | There's a bunch of variations for `INTERACTIVE`, 524 | [see the manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Using-Interactive.html). 525 | 526 | Now your function `foo` is interactive, you can use it in a 527 | keybinding: 528 | 529 | ``` lisp 530 | (define-key emacs-lisp-mode (kbd "C-c C-f") 'foo) 531 | ``` 532 | 533 | ## Defining your own major mode 534 | 535 | You can generally use `define-derived-mode`. See 536 | [the manual on this.](http://www.gnu.org/software/emacs/manual/html_node/elisp/Derived-Modes.html) 537 | 538 | Example: 539 | 540 | ``` lisp 541 | (define-derived-mode hypertext-mode 542 | text-mode "Hypertext" 543 | "Major mode for hypertext. 544 | \\{hypertext-mode-map}" 545 | (setq case-fold-search nil)) 546 | 547 | (define-key hypertext-mode-map 548 | [down-mouse-3] 'do-hyper-link) 549 | ``` 550 | 551 | ## Defining a minor mode 552 | 553 | Minor modes act as enhancements to existing modes. See 554 | [the manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Minor-Modes.html) 555 | about `define-minor-mode`. 556 | 557 | A dummy example: 558 | 559 | ``` lisp 560 | (defvar elisp-guide-mode-map (make-sparse-keymap)) 561 | (define-minor-mode elisp-guide-mode "A simple minor mode example." 562 | :lighter " ELGuide" 563 | :keymap elisp-guide-mode-map 564 | (if (bound-and-true-p elisp-guide-mode) 565 | (message "Elisp guide activated!") 566 | (message "Bye!"))) 567 | (define-key elisp-guide-mode-map (kbd "C-c C-a") 'elisp-guide-go) 568 | (defun elisp-guide-go () 569 | (interactive) 570 | (message "Go!")) 571 | ``` 572 | 573 | Run `M-x elisp-guide-mode` to activate it and run it again to disable it. 574 | 575 | Real examples of minor modes: 576 | 577 | * [structured-haskell-mode](https://github.com/chrisdone/structured-haskell-mode/blob/master/elisp/shm.el#L110) 578 | * [paredit-mode](https://github.com/emacsmirror/paredit/blob/master/paredit.el#L203) 579 | * [god-mode](https://github.com/chrisdone/god-mode/blob/master/god-mode.el#L80..L86) 580 | 581 | ## Markers 582 | 583 | Markers are handy objects that store a point, and changes to the 584 | buffer make the marker position move along. See 585 | [the manual](http://www.gnu.org/software/emacs/manual/html_node/elisp/Markers.html), 586 | which has a good section explaining it. Their use-case is probably 587 | more intermediate than for a tutorial like this, so I include them 588 | only so that you're aware of them. 589 | 590 | Here's an example: 591 | 592 | ``` lisp 593 | (defun my-indent-region (beg end) 594 | (interactive "r") 595 | (let ((marker (make-marker))) 596 | (set-marker marker (region-end)) 597 | (goto-char (region-beginning)) 598 | (while (< (point) marker) 599 | (funcall indent-line-function) 600 | (forward-line 1)))) 601 | ``` 602 | 603 | You need to store the end of the region before you start changing the 604 | buffer, because the integer position will increase as you start 605 | indenting lines. So you store it in a marker and that marker's value 606 | updates as the buffer's contents changes. 607 | 608 | ## Overlays 609 | 610 | See 611 | [the manual on overlays](http://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html), 612 | these are a handy tool for a special kind of text that behaves as if 613 | separate and above the buffer. This is more advanced, by the time you 614 | want to use overlays you'll be happy reading the manual entry about it. 615 | 616 | ## Standard practices 617 | 618 | ### Namespacing 619 | 620 | Emacs Lisp doesn't support modules. We go by convention. If your 621 | module name is `foo`, then name all your top-level bindings by 622 | prefixing it with `foo-`. Example: 623 | 624 | (defun foo-go () 625 | "Go!" 626 | ...) 627 | 628 | (provide 'foo) 629 | 630 | To make this easier on your fingers, you can use something like: 631 | 632 | ``` lisp 633 | (defun emacs-lisp-expand-clever () 634 | "Cleverly expand symbols with normal dabbrev-expand, but also 635 | if the symbol is -foo, then expand to module-name-foo." 636 | (interactive) 637 | (if (save-excursion 638 | (backward-sexp) 639 | (when (looking-at "#?'") (search-forward "'")) 640 | (looking-at "-")) 641 | (if (eq last-command this-command) 642 | (call-interactively 'dabbrev-expand) 643 | (let ((module-name (emacs-lisp-module-name))) 644 | (progn 645 | (save-excursion 646 | (backward-sexp) 647 | (when (looking-at "#?'") (search-forward "'")) 648 | (unless (string= (buffer-substring-no-properties 649 | (point) 650 | (min (point-max) (+ (point) (length module-name)))) 651 | module-name) 652 | (insert module-name))) 653 | (call-interactively 'dabbrev-expand)))) 654 | (call-interactively 'dabbrev-expand))) 655 | 656 | (defun emacs-lisp-module-name () 657 | "Search the buffer for `provide' declaration." 658 | (save-excursion 659 | (goto-char (point-min)) 660 | (when (search-forward-regexp "^(provide '" nil t 1) 661 | (symbol-name (symbol-at-point))))) 662 | ``` 663 | 664 | And then: 665 | 666 | ``` lisp 667 | (define-key emacs-lisp-mode-map (kbd "M-/") 'emacs-lisp-expand-clever) 668 | ``` 669 | 670 | Now you can write `(defun -blah M-/` and get `(defun foo-blah`. You 671 | need a `(provide 'foo)` line at the bottom of your file for this to work. 672 | 673 | ## Alternative sources 674 | 675 | * http://steve-yegge.blogspot.it/2008/01/emergency-elisp.html 676 | * http://lispp.wordpress.com/2009/11/25/emacs-lisp-cheatsheet/ 677 | * http://stackoverflow.com/questions/5238245/elisp-programming-whats-the-best-setup 678 | * http://nic.ferrier.me.uk/blog/2012_07/tips-and-tricks-for-emacslisp 679 | * https://www.gnu.org/software/emacs/manual/html_node/eintr/index.html 680 | * http://www.emacswiki.org/emacs/EmacsLispIntro 681 | * http://www.emacswiki.org/emacs/LearnEmacsLisp 682 | * http://bzg.fr/learn-emacs-lisp-in-15-minutes.html 683 | * http://www.delorie.com/gnu/docs/emacs-lisp-intro/emacs-lisp-intro_toc.html 684 | * http://cjohansen.no/an-introduction-to-elisp 685 | * http://emacswiki.org/emacs/ElispCookbook 686 | * [Emacs cheah sheet](https://web.archive.org/web/20150525182115/http://wikemacs.org/wiki/Emacs_Lisp_Cheat_Sheet) -------------------------------------------------------------------------------- /README.org: -------------------------------------------------------------------------------- 1 | * Emacs Lisp Guide 2 | 3 | ** Table of Contents 4 | * [[*Audience][Audience]] 5 | * [[*Programming in Emacs Lisp][Programming in Emacs Lisp]] 6 | * [[*After reading this guide][After reading this guide]] 7 | * [[*Trivial basics][Trivial basics]] 8 | * [[*Evaluation][Evaluation]] 9 | * [[*Discoverability][Discoverability]] 10 | * [[*Finding functions of keybindings][Finding functions of keybindings]] 11 | * [[*Getting documentation][Getting documentation]] 12 | * [[*Find all bindings in the current buffer][Find all bindings in the current buffer]] 13 | * [[*Searching for documentation topics][Searching for documentation topics]] 14 | * [[*Jumping to definition][Jumping to definition]] 15 | * [[*Describe functions][Describe functions]] 16 | * [[*Basic concepts][Basic concepts]] 17 | * [[*Buffers][Buffers]] 18 | * [[*Buffer-local variables][Buffer-local variables]] 19 | * [[*Project-wide buffer-local variables][Project-wide buffer-local variables]] 20 | * [[*The point][The point]] 21 | * [[*The region][The region]] 22 | * [[*Text properties][Text properties]] 23 | * [[*Debugging][Debugging]] 24 | * [[*Editing][Editing]] 25 | * [[*Paredit][Paredit]] 26 | * [[*Manipulating the buffer][Manipulating the buffer]] 27 | * [[*Navigating the buffer][Navigating the buffer]] 28 | * [[*Querying the buffer][Querying the buffer]] 29 | * [[*Temporary buffers][Temporary buffers]] 30 | * [[*Defining interactive functions][Defining interactive functions]] 31 | * [[*Defining your own major mode][Defining your own major mode]] 32 | * [[*Defining a minor mode][Defining a minor mode]] 33 | * [[*Markers][Markers]] 34 | * [[*Overlays][Overlays]] 35 | * [[*Standard practices][Standard practices]] 36 | * [[*Alternative sources][Alternative sources]] 37 | 38 | ** Audience 39 | 40 | Programmers who are too busy to read through long tutorials and 41 | manuals, but who want to extend their editor. You don't need to learn 42 | everything from the ground up, just enough knowledge to be 43 | self-sufficient. You've been using Emacs for a while and now it's time 44 | you started making some handy extensions for yourself. 45 | 46 | There are a bunch of existing guides, but they don't strike the right 47 | balance of useful and helpful. Some just list functions, others try to 48 | explain Emacs Lisp from the ground up as a language. You don't need to 49 | know everything right away. See the [Alternative sources](#alternative-sources) 50 | section for a list of these. 51 | 52 | ** Programming in Emacs Lisp 53 | 54 | I'm not going to explain the Emacs Lisp language itself in any detail. 55 | Programming in [[http://en.wikipedia.org/wiki/Emacs_Lisp][Emacs Lisp]] (look at the Wikipedia page for the academic details) 56 | is similar to programming in Python, Scheme, Common Lisp, JavaScript, Ruby, and 57 | languages like that. Its syntax is funny but otherwise it's an imperative 58 | language with similar data structures. 59 | 60 | **One important difference** compared to usual languages to be aware of is that it 61 | has _dynamic scope_ by default. See [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Binding.html#Dynamic-Binding][Dynamic Binding]] in the manual for the details. 62 | Almost all Emacs Lisp code you come across today will be using this. [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html#Lexical-Binding][Lexical 63 | Binding]] has recently been added to Emacs, it will take a while for this to 64 | permeate. 65 | 66 | Like all Lisps, Emacs Lisp has macros which you can [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Macros.html#Macros][read about in the manual at 67 | your leisure]] 68 | 69 | ** After reading this guide 70 | 71 | The best, most comprehensive resource on Emacs Lisp is [[https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html][the manual]]. I will 72 | reference this manual throughout this guide. I will not repeat what's already 73 | there. You can reference this manually in a random access fashion when you need 74 | to solve a problem. 75 | 76 | I reference the manual throughout the guide by HTML link, but you can 77 | read it inside your Emacs itself. Run: `C-h i m Elisp RET` 78 | 79 | ** Trivial basics 80 | 81 | These are the basics to syntax that you can lookup in any guide or 82 | just by looking at some Emacs Lisp code. I am assuming you're a 83 | programmer who can pick things up like this just by looking at code. I 84 | include these because I use them later: 85 | 86 | #+BEGIN_SRC emacs-lisp 87 | (* 2 3) 88 | (concat "a" "b") 89 | (defun func (arg1 arg2) 90 | "Always document your functions." 91 | ) 92 | (defvar var-name 93 | "Always document your variables.") 94 | (let ((x 1) 95 | (y 2)) 96 | ...) 97 | #+END_SRC 98 | 99 | In Lisp the normal `LET` doesn't let you refer to previous variables, 100 | so you need to use `LET*` for that. This is likely to trip people up, 101 | so I include it here. 102 | 103 | #+BEGIN_SRC emacs-lisp 104 | (let* ((x 1) 105 | (y x)) 106 | ...) 107 | #+END_SRC 108 | 109 | To do many things at once in one expression, use `PROGN`: 110 | 111 | #+BEGIN_SRC emacs-lisp 112 | (progn do-this 113 | do-that) 114 | #+END_SRC 115 | 116 | [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Local-Variables.html#Local-Variables][See manual]] for details. 117 | 118 | The way to set variables is not obvious: 119 | 120 | #+BEGIN_SRC emacs-lisp 121 | (setq var-name value) 122 | 123 | #+END_SRC 124 | 125 | Equality and comparison operators: 126 | 127 | * `(eq major-mode 'a)` 128 | * `(= 0 1)` 129 | * `(> 0 1)` 130 | * `(string= "a" "b")` 131 | * `(string> "a" "b")` 132 | 133 | Emacs Lisp has a bunch of equality operators. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Equality-Predicates.html][the manual]] for gory details. 134 | 135 | Data structures available: lists, vectors, rings, hashtables. Look them up in 136 | [[https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html][the manual]]. 137 | 138 | ** Evaluation 139 | 140 | * Use `M-:` to evaluate any Emacs Lisp expression and print the 141 | result. I personally use this constantly. 142 | * Use `C-x C-e` to evaluate the previous s-expression in the 143 | buffer. I personally never use this. See next binding. 144 | * Use `C-M-x` to evaluate the current top-level s-expression. I use 145 | this to re-apply `defvar` and `defun` declarations. 146 | * There is a REPL available by `M-x ielm`. I tend to use `M-:` rather 147 | than the REPL but you might like it. 148 | * Use `M-x eval-buffer` to evaluate the whole buffer of Emacs Lisp 149 | code. 150 | 151 | ** Discoverability 152 | 153 | A very important thing as an Emacs Lisp programmer is being able to 154 | get the information you want in a few keystrokes. Here's a list of 155 | ways to find what you need when you're writing Elisp code. 156 | 157 | *** Finding functions of keybindings 158 | 159 | Find the function called by a keybinding: `C-h k` 160 | 161 | This will show something like: 162 | 163 | C-p runs the command previous-line, which is an interactive compiled 164 | Lisp function in `simple.el'. 165 | 166 | It is bound to C-p. 167 | 168 | (previous-line &optional ARG TRY-VSCROLL) 169 | 170 | You can click the link `simple.el` to go directly to the definition of 171 | that function. Very handy indeed. 172 | 173 | *** Getting documentation 174 | 175 | Functions and variables are distinguished in Emacs Lisp, so there are 176 | two commands to do lookups: 177 | 178 | * Run `C-h f` to show documentation for a function. This also works 179 | for macros. 180 | * Run `C-h v` to show documentation for a variable. 181 | 182 | You'll see something like: 183 | 184 | mapcar is a built-in function in `C source code'. 185 | 186 | (mapcar FUNCTION SEQUENCE) 187 | 188 | Apply FUNCTION to each element of SEQUENCE, and make a list of the results. 189 | The result is a list just as long as SEQUENCE. 190 | SEQUENCE may be a list, a vector, a bool-vector, or a string. 191 | 192 | *** Find all bindings in the current buffer 193 | 194 | Run `C-h b` to show a massive list of keybindings and the command they 195 | run. You'll see something like, e.g. in `markdown-mode`: 196 | 197 | C-c C-x d markdown-move-down 198 | C-c C-x l markdown-promote 199 | C-c C-x m markdown-insert-list-item 200 | 201 | *** Searching for documentation topics 202 | 203 | Use the commands called `apropos`. 204 | 205 | * `M-x apropos` 206 | * `M-x apropos-command` 207 | * `M-x apropos-library` 208 | * `M-x apropos-documentation` 209 | 210 | *** Jumping to definition 211 | 212 | Install this package: 213 | [[https://github.com/purcell/elisp-slime-nav][elisp-slime-nav]] 214 | 215 | Now you can use `M-.` to jump to the identifer at point and `M-,` to 216 | jump back. 217 | 218 | *** Describe functions 219 | 220 | The range of `M-x describe-` functions are useful: 221 | 222 | * `M-x describe-mode` (aka `C-h m`) 223 | * `M-x describe-face` 224 | 225 | Other ones have been mentioned above as keybindings. 226 | 227 | ** Basic concepts 228 | 229 | *** Buffers 230 | 231 | All Emacs Lisp code when run has a current buffer. Operations that 232 | claim to work on "the buffer" work on this current buffer. Some handy 233 | functions, which you can run `C-h f` on to get more info: 234 | 235 | * `(current-buffer)` - get the current buffer. 236 | * `(with-current-buffer buffer-or-name ...)` - temporarily use the given buffer. 237 | * `(set-buffer buffer-or-name)` - set the current buffer without 238 | switching to it. 239 | * `(switch-to-buffer name)` - switch to the buffer visually. 240 | 241 | See [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffers.html#Buffers][Buffers]] in the manual for detailed info. 242 | 243 | *** Buffer-local variables 244 | 245 | Buffers have local variables, for example: 246 | 247 | * major-mode 248 | 249 | You can use this variable to see what mode you're in, if you need it. 250 | 251 | If you want to set your own buffer-local variable, use this: 252 | 253 | #+BEGIN_SRC emacs-lisp 254 | (defvar your-variable-name nil "Your documentation here.") 255 | #+END_SRC 256 | 257 | Then later on in your code that will run in a given buffer, use: 258 | 259 | #+BEGIN_SRC emacs-lisp 260 | (set (make-local-variable 'your-variable-name) ) 261 | #+END_SRC 262 | 263 | This is very handy in many scenarios when writing functionality. Note 264 | that buffer local variables are reset when you revert the buffer or 265 | change modes. 266 | 267 | See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer_002dLocal-Variables.html#Buffer_002dLocal-Variables][manual]] for details. 268 | 269 | *** Project-wide buffer-local variables 270 | 271 | A handy way to set a buffer local variable for every file that's within a 272 | directory structure is to use [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][a `.dir-locals.el` file.]] 273 | 274 | #+BEGIN_SRC emacs-lisp 275 | ((nil . ((indent-tabs-mode . t) 276 | (fill-column . 80))) 277 | (c-mode . ((c-file-style . "BSD") 278 | (subdirs . nil))) 279 | ("src/imported" 280 | . ((nil . ((change-log-default-name 281 | . "ChangeLog.local")))))) 282 | #+END_SRC 283 | 284 | *** The point 285 | 286 | All Emacs Lisp code has a current point in the current buffer. It's a number. 287 | It refers to where the cursor is. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Point.html][the manual entry for point]], but here's 288 | the basics: 289 | 290 | * `(point)` - current point 291 | * `(point-max)` - maximum point of the buffer 292 | * `(point-min)` - minimum point of the buffer (why is this not just `0`? 293 | Because of [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Narrowing.html#Narrowing][narrowing]]. 294 | 295 | *** The region 296 | 297 | Sometimes the region can be active, and you can use it in your Emacs Lisp code 298 | to manipulate text specially. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/The-Region.html#The-Region][the manual]] for details. Rundown: 299 | 300 | * `(region-beginning)` - beginning of the region (a point) 301 | * `(region-end)` - end of the region (a point) 302 | * `(use-region-p)` - whether to try to use region-beginning/region-end 303 | for manipulation. Handy for use in commands. 304 | * `(region-active-p)` - also handy to know whether the region is 305 | active. 306 | 307 | Here's an command that uses some region functions: 308 | 309 | #+BEGIN_SRC emacs-lisp 310 | (defun print-upper-region () 311 | "Demo to print the uppercased version of the active region." 312 | (interactive) 313 | (when (region-active-p) 314 | (message "%S" (let ((string (buffer-substring (region-beginning) 315 | (region-end)))) 316 | (with-temp-buffer 317 | (insert string) 318 | (upcase-region (point-min) 319 | (point-max)) 320 | (buffer-substring-no-properties (point-min) 321 | (point-max))))))) 322 | #+END_SRC 323 | 324 | To run it, `C-M-x` it, select some text and run `M-x print-upper-region`. 325 | 326 | *** Text properties 327 | 328 | When you manipulate text in Elisp, it can have properties applied to it, and 329 | those properties can be queried. Full details are [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Text-Properties.html#Text-Properties][here]] but see the "Manipulating 330 | the buffer" section in this guide for examples. 331 | 332 | ** Debugging 333 | 334 | Run `M-: (setq debug-on-error t) RET` and any errors will open up the 335 | debugger. 336 | 337 | I'll write more about using the debugger stepper and breakpoints later. 338 | 339 | ** Editing 340 | 341 | *** Paredit 342 | 343 | Install and enable [[http://www.emacswiki.org/emacs/ParEdit][paraedit]]. Nobody sane writes Lisp without paredit (or its 344 | shiny cousin, [[https://github.com/Fuco1/smartparens][smartparens]]; or its evil twin, [[https://github.com/abo-abo/lispy][lispy]]. You will never have 345 | unbalanced parentheses, brackets, braces, or strings. Learn to accept this and 346 | you will enjoy this mode. 347 | 348 | As discussed in the discoverability section, use `C-h f paredit-mode 349 | RET` to see the documentation for this mode. 350 | 351 | Learn the following helpful keybindings: 352 | 353 | **** Navigating 354 | 355 | * `C-M-u` - Go up a node. 356 | * `)` - Go to the end of the node or the end of the parent node when repeated. 357 | * `C-M-f` - Go to the end of the node. 358 | * `C-M-b` - Go to the start of the node. 359 | 360 | **** Killing 361 | 362 | `C-k` - Kill everything from here to the end of the line, including 363 | any following lines that are included in the scope of the nodes 364 | being killed. It will also kill inside strings but stop at the end 365 | of the string. 366 | 367 | **** Raising 368 | 369 | `M-r` - Replace the parent node by the current node. 370 | 371 | (|foo) -> foo 372 | (foo |bar mu) -> bar 373 | (foo (bar |mu zot) bob) -> (foo mu bob) 374 | 375 | **** Wrapping 376 | 377 | * `C-M-(` to wrap the following node in parens. 378 | * Alternatively, `C-M-SPC` to select the whole node, or just use your 379 | normal region selection and run `(` or 380 | `[` or `{` to wrap that selection. 381 | 382 | **** Splitting 383 | 384 | * `M-s` to split the current node. This works on parenthesized expressions or strings. 385 | * `M-J` to join two nodes. Works same as above in reverse. 386 | 387 | ** Manipulating the buffer 388 | 389 | These are the most common: 390 | 391 | * `(insert "foo" "bar")` - to insert text at point. 392 | * `(delete-region start end)` - to delete the region of text. 393 | * `(insert-buffer-substring-no-properties buffer start end)` - insert text from another buffer. 394 | * `(insert-file-contents )` - insert from a file. 395 | 396 | Any other command that inserts things can be called from Emacs Lisp, too. 397 | 398 | *** Text properties 399 | 400 | To add properties to text in the buffer, use: 401 | 402 | #+BEGIN_SRC emacs-lisp 403 | (put-text-property start end 'my-property-name ) 404 | #+END_SRC 405 | 406 | To completely reset the properties of text to just this, use: 407 | 408 | #+BEGIN_SRC emacs-lisp 409 | (set-text-properties start end 'my-property-name ) 410 | #+END_SRC 411 | 412 | To retrieve properties back from the text, use: 413 | 414 | #+BEGIN_SRC emacs-lisp 415 | (get-text-property 'my-property-name) 416 | #+END_SRC 417 | 418 | To propertize a string before it's inserted into a buffer, use: 419 | 420 | #+BEGIN_SRC emacs-lisp 421 | (propertize "hello" 'my-property-name 'another-prop ) 422 | 423 | #+END_SRC 424 | 425 | ** Navigating the buffer 426 | 427 | Here are the common ones: 428 | 429 | * `(goto-char )` - go to the point. 430 | * `(forward-char n)` - go forward n chars. Accepts a negative argument. 431 | * `(end-of-line)` - self-explanatory. 432 | * `(beginning-of-line)` - self-explanatory. 433 | * `(skip-chars-forward "chars")` - skip given chars. 434 | * `(skip-chars-backward "chars")` - skip given chars back. 435 | * `(search-forward "foo")` - search for foo, move cursor there. 436 | * `(search-backward "foo")` - search backward. 437 | * `(search-forward-regexp "blah")` - same, but with regexes. 438 | * `(search-backward-regexp "blah")` - same, but with regexes. 439 | 440 | If there's a kind of navigation you want to do that you don't know the function name for, think of how you would do it with your keyboard and then use `C-h k` on the commands to find out the functions being run. 441 | 442 | *** Save excursion 443 | 444 | Often you want to jump around the buffer to either query or manipulate something, and then go back to where you were originally. To do this, use: 445 | 446 | #+BEGIN_SRC emacs-lisp 447 | (save-excursion ...) 448 | #+END_SRC 449 | 450 | For example: 451 | 452 | #+BEGIN_SRC emacs-lisp 453 | (save-excursion (beginning-of-line) (looking-at "X")) 454 | #+END_SRC 455 | 456 | Will return whether the current line starts with `X`. 457 | 458 | Similarly there is `save-window-excursion`. 459 | 460 | ** Querying the buffer 461 | 462 | * `(buffer-substring start end)` - get the string at point, including text properties. 463 | * `(buffer-substring-no-properties start end)` - get the string at point, excluding text properties. 464 | * `(buffer-string)` - return the string of the whole buffer. 465 | * `(looking-at "[a-zA-Z]+")` - does text following point match the regex? 466 | * `(looking-back "[a-zA-Z]+")` - does text preceding point match the regex? 467 | 468 | ** Temporary buffers 469 | 470 | It's often useful to do some work in a temporary buffer so that you 471 | can use your normal Elisp code to generate a string and some 472 | properties, for example: 473 | 474 | #+BEGIN_SRC emacs-lisp 475 | (with-temp-buffer 476 | (insert "Hello!")) 477 | #+END_SRC 478 | 479 | ** Defining interactive functions 480 | 481 | To be able to run a function of your own from a keybinding, it needs 482 | to be interactive. You need to add `(interactive)` to your `defun`: 483 | 484 | #+BEGIN_SRC emacs-lisp 485 | (defun foo () 486 | "Some function." 487 | (interactive) 488 | (do-some-stuff)) 489 | #+END_SRC 490 | 491 | There's a bunch of variations for `INTERACTIVE`, [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Using-Interactive.html][see the manual]]. 492 | 493 | Now your function `foo` is interactive, you can use it in a 494 | keybinding: 495 | 496 | #+BEGIN_SRC emacs-lisp 497 | (define-key emacs-lisp-mode (kbd "C-c C-f") 'foo) 498 | #+END_SRC 499 | 500 | ** Defining your own major mode 501 | 502 | You can generally use `define-derived-mode`. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Derived-Modes.html][the manual on this.]] 503 | 504 | Example: 505 | 506 | #+BEGIN_SRC emacs-lisp 507 | (define-derived-mode hypertext-mode 508 | text-mode "Hypertext" 509 | "Major mode for hypertext. 510 | \\{hypertext-mode-map}" 511 | (setq case-fold-search nil)) 512 | 513 | (define-key hypertext-mode-map 514 | [down-mouse-3] 'do-hyper-link) 515 | #+END_SRC 516 | 517 | ** Defining a minor mode 518 | 519 | Minor modes act as enhancements to existing modes. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Minor-Modes.html][the manual]] about 520 | `define-minor-mode`. 521 | 522 | A dummy example: 523 | 524 | #+BEGIN_SRC emacs-lisp 525 | (defvar elisp-guide-mode-map (make-sparse-keymap)) 526 | (define-minor-mode elisp-guide-mode "A simple minor mode example." 527 | :lighter " ELGuide" 528 | :keymap elisp-guide-mode-map 529 | (if (bound-and-true-p elisp-guide-mode) 530 | (message "Elisp guide activated!") 531 | (message "Bye!"))) 532 | (define-key elisp-guide-mode-map (kbd "C-c C-a") 'elisp-guide-go) 533 | (defun elisp-guide-go () 534 | (interactive) 535 | (message "Go!")) 536 | #+END_SRC 537 | 538 | Run `M-x elisp-guide-mode` to activate it and run it again to disable it. 539 | 540 | Real examples of minor modes: 541 | 542 | * [[https://github.com/chrisdone/structured-haskell-mode/blob/master/elisp/shm.el#L110][structured-haskell-mode]] 543 | * [[https://github.com/emacsmirror/paredit/blob/master/paredit.el#L203][paredit-mode]] 544 | * [[https://github.com/chrisdone/god-mode/blob/master/god-mode.el#L80..L86][god-mode]] 545 | 546 | ** Markers 547 | 548 | Markers are handy objects that store a point, and changes to the buffer make the 549 | marker position move along. See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Markers.html][the manual]], which has a good section explaining 550 | it. Their use-case is probably more intermediate than for a tutorial like this, 551 | so I include them only so that you're aware of them. 552 | 553 | Here's an example: 554 | 555 | #+BEGIN_SRC emacs-lisp 556 | (defun my-indent-region (beg end) 557 | (interactive "r") 558 | (let ((marker (make-marker))) 559 | (set-marker marker (region-end)) 560 | (goto-char (region-beginning)) 561 | (while (< (point) marker) 562 | (funcall indent-line-function) 563 | (forward-line 1)))) 564 | #+END_SRC 565 | 566 | You need to store the end of the region before you start changing the 567 | buffer, because the integer position will increase as you start 568 | indenting lines. So you store it in a marker and that marker's value 569 | updates as the buffer's contents changes. 570 | 571 | ** Overlays 572 | 573 | See [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html][the manual on overlays]], these are a handy tool for a special kind of text 574 | that behaves as if separate and above the buffer. This is more advanced, by the 575 | time you want to use overlays you'll be happy reading the manual entry about it. 576 | 577 | ** Standard practices 578 | 579 | *** Namespacing 580 | 581 | Emacs Lisp doesn't support modules. We go by convention. If your 582 | module name is `foo`, then name all your top-level bindings by 583 | prefixing it with `foo-`. Example: 584 | 585 | (defun foo-go () 586 | "Go!" 587 | ...) 588 | 589 | (provide 'foo) 590 | 591 | To make this easier on your fingers, you can use something like: 592 | 593 | #+BEGIN_SRC emacs-lisp 594 | (defun emacs-lisp-expand-clever () 595 | "Cleverly expand symbols with normal dabbrev-expand, but also 596 | if the symbol is -foo, then expand to module-name-foo." 597 | (interactive) 598 | (if (save-excursion 599 | (backward-sexp) 600 | (when (looking-at "#?'") (search-forward "'")) 601 | (looking-at "-")) 602 | (if (eq last-command this-command) 603 | (call-interactively 'dabbrev-expand) 604 | (let ((module-name (emacs-lisp-module-name))) 605 | (progn 606 | (save-excursion 607 | (backward-sexp) 608 | (when (looking-at "#?'") (search-forward "'")) 609 | (unless (string= (buffer-substring-no-properties 610 | (point) 611 | (min (point-max) (+ (point) (length module-name)))) 612 | module-name) 613 | (insert module-name))) 614 | (call-interactively 'dabbrev-expand)))) 615 | (call-interactively 'dabbrev-expand))) 616 | 617 | (defun emacs-lisp-module-name () 618 | "Search the buffer for `provide' declaration." 619 | (save-excursion 620 | (goto-char (point-min)) 621 | (when (search-forward-regexp "^(provide '" nil t 1) 622 | (symbol-name (symbol-at-point))))) 623 | #+END_SRC 624 | 625 | And then: 626 | 627 | #+BEGIN_SRC emacs-lisp 628 | (define-key emacs-lisp-mode-map (kbd "M-/") 'emacs-lisp-expand-clever) 629 | #+END_SRC 630 | 631 | Now you can write `(defun -blah M-/` and get `(defun foo-blah`. You 632 | need a `(provide 'foo)` line at the bottom of your file for this to work. 633 | 634 | ** Alternative sources 635 | 636 | * https://github.com/gar3thjon3s/elisp-cheatsheet/blob/master/cheatsheet.md 637 | * http://wikemacs.org/wiki/Emacs_Lisp_Cheat_Sheet 638 | * http://steve-yegge.blogspot.it/2008/01/emergency-elisp.html 639 | * http://lispp.wordpress.com/2009/11/25/emacs-lisp-cheatsheet/ 640 | * http://stackoverflow.com/questions/5238245/elisp-programming-whats-the-best-setup 641 | * http://nic.ferrier.me.uk/blog/2012_07/tips-and-tricks-for-emacslisp 642 | * https://www.gnu.org/software/emacs/manual/html_node/eintr/index.html 643 | * http://www.emacswiki.org/emacs/EmacsLispIntro 644 | * http://www.emacswiki.org/emacs/LearnEmacsLisp 645 | * http://bzg.fr/learn-emacs-lisp-in-15-minutes.html 646 | * http://www.delorie.com/gnu/docs/emacs-lisp-intro/emacs-lisp-intro_toc.html 647 | * http://cjohansen.no/an-introduction-to-elisp 648 | * http://emacswiki.org/emacs/ElispCookbook 649 | --------------------------------------------------------------------------------