# -*- mode: org -*- #+TITLE: "How can I try Emacs Lisp code?" #+OPTIONS: toc:t #+STARTUP: showall #+BEGIN_CONVENTIONS Some conventions we'll use: - Inline code will be =boxed and monospace= in the HTML version and generally surrounded by =equal signs= in plain text. - Code samples will be monospace and in boxes in the HTML version, and enclosed in =#+begin_src= ... =#+end_src= in plain text. Example: #+begin_src emacs-lisp (message "Hello world") #+end_src #+END_CONVENTIONS #+BEGIN_OBJECTIVES After this section, you should be able to - find Emacs Lisp code to study and use - try Emacs Lisp code before saving it to your configuration (that way, you don't have to keep restarting Emacs) - add code to your configuration so that it runs whenever Emacs starts #+END_OBJECTIVES * Finding Emacs Lisp code 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: ** Emacs documentation Manuals and FAQs for Emacs-related tools often include code snippets. For example, the [[https://www.gnu.org/software/emacs/manual/efaq.html][Emacs FAQ]] has an entry like this: #+begin_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) #+end_example You can read the Emacs manual by typing =C-h i= (=info=) and choosing the *Emacs* item. If you're on a terminal that doesn't understand the =C-h= key, use =F1= or =M-x help= whenever you see a reference to =C-h=, or use =M-x= to call the command by name (ex: =F1 i=, or =M-x info=). To jump directly to the Emacs manual, you can use =C-h r= (=info-emacs-manual=). You can also find the Emacs Manual at http://www.gnu.org/software/emacs/manual/emacs.html . ** Packages 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 =M-x package-list-packages= to list the packages that Emacs knows about by default. You will need an Internet connection for that. 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. In addition to the default package repository, there are other community-supported repositories. See [[http://emacslife.com/how-to-read-emacs-lisp.html#installing-packages][Installing packages]] if you would like to install a package from a different repository. 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. Here are some packages that might be interesting: - company: adds text completion - yasnippet: snippets and templates - undo-tree: visualize your undo/redo history You will need to be connected to the Internet in order to view and install packages. You can use =M-x package-list-packages= to show the available packages and read the descriptions for the packages above. ** Webpages, blog posts, and the Emacs Wiki While searching for information related to Emacs, you'll probably come across lots of Emacs Lisp snippets. The [[http://www.emacswiki.org/][EmacsWiki]] 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 [[http://emacslife.com/how-to-read-emacs-lisp.html#errors]["Oh no! I have an error!"]] Here are some sites you may want to check out: - EmacsWiki: CategoryDotEmacs - http://www.emacswiki.org/emacs/CategoryDotEmacs - Emacs Redux - http://emacsredux.com - What the Emacs.d?! - http://whattheemacsd.com/ - The very unofficial .emacs home - http://www.dotemacs.de/localfiles.html ** Mailing lists, newsgroups, and Q&A sites There are many places where you can ask for help with Emacs. gnu.emacs.help is available as a [[https://lists.gnu.org/mailman/listinfo/help-gnu-emacs][mailing list]] or as a newsgroup - check your favourite Usenet server or use [[http://dir.gmane.org/gmane.emacs.help][Gmane]]. [[http://stackoverflow.com/questions/tagged/emacs][StackOverflow]] and [[http://www.quora.com/Emacs][Quora]] 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. Find a snippet of Emacs Lisp code you want to understand more deeply, or look at the examples in the sections below. * Trying out code It's easier to understand code if you can experiment with it. Emacs Lisp code is made up of *symbolic expressions* (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. Note: As you experiment with Emacs Lisp, you might run into errors. Check out [[http://emacslife.com/how-to-read-emacs-lisp.html#errors]["Oh no! I have an error!"]] for some common errors and what to do about them. Here are some ways you can run Emacs Lisp code. I'll explain them in more detail below. - =M-x ielm= (Inferior Emacs Lisp Mode) - evaluates expressions after you press =RET=, which is handy for pasting in code - The =*scratch*= buffer and Emacs Lisp files - makes it easy to edit and re-evaluate expressions - =M-:= (=eval-expression=) - good for quickly evaluating Emacs Lisp code while you're doing something else - =C-x C-e= (=eval-last-sexp=) - handy when reading expressions in manuals or other text ** M-x ielm (Inferior Emacs Lisp Mode) The Inferior Emacs Lisp Mode gives you a prompt where you can type or paste in Emacs Lisp code. Start it with =M-x ielm=. Press =RET= 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 =RET= to run (or "evaluate") it again. If you're copying or typing code, make sure your parentheses are all matched - every "=(=" should have a "=)=". IELM won't run the code unless it sees the closing parenthesis. So the following code is incomplete: #+begin_src emacs-lisp :eval no (message "Hello #+end_src but this will work: #+begin_src emacs-lisp (message "Hello world") #+end_src You can use =M-p= (=comint-previous-input=) to go through the previously-typed expressions. =M-n= (=comint-next-input=) goes forward. Tip: When you're trying out an unfamiliar mode, use =C-h m= (=describe-mode=) to learn more about the commands that are available in that mode. ** The =*scratch*= buffer and Emacs Lisp =.el= files When Emacs starts, it creates a buffer called =*scratch*= with the following contents: #+begin_src emacs-lisp ;; This buffer is for notes you don't want to save, and for Lisp evaluation. ;; If you want to create a file, visit that file with C-x C-f, ;; then enter the text in that file's own buffer. #+end_src You can add code to the end. #+begin_src emacs-lisp ;; This buffer is for notes you don't want to save, and for Lisp evaluation. ;; If you want to create a file, visit that file with C-x C-f, ;; then enter the text in that file's own buffer. (message "Hello world") #+end_src Note: =;= 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. =;;= above is how we usually start comments that take up the entire line. To run code ("evaluate" it, in Emacs terms), you can use the following commands based on what you want to run: - =M-x eval-buffer= runs all the code in the current file or buffer. - =M-x eval-region= runs the code in the selected region. You can select a region of text by using the mouse. Alternatively, you can type =C-SPC= 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 (=C-h t=, =C-h t=, or =M-x help-with-tutorial=). - =C-x C-e= (=eval-last-sexp=) runs the expression (S-expression, or sexp) before the cursor. NOTE: Your cursor should be after the closing parenthesis, not on it. In the =*scratch*= buffer, you can also press =C-j= (=eval-print-last-sexp=) after an expression in order to evaluate it and display the results in the buffer. The =*scratch*= buffer is not automatically saved. If you would like to save your code for future use, you can create a file with an =.el= ending. =el= stands for Emacs Lisp, and Emacs will open these files in Emacs Lisp mode. The commands listed above work in Emacs Lisp files. ** M-: (eval-expression) If you want to quickly try a single expression, you can use =M-:= (=eval-expression=). 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 =C-u M-:= instead. For example, you can use =C-u M-: (* 18 2)= to multiply 18 and 2 quickly. To review previous results, you can switch to the =*Messages*= buffer. ** C-x C-e (eval-last-sexp) =C-x C-e= (=eval-last-sexp=) runs the expression (S-expression, or sexp) before the cursor. NOTE: Your cursor should be after the closing parenthesis, not on it. =C-x C-e= (=eval-last-sexp=) 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. You can get the text file for this lesson from http://emacslife.com/read-lisp-tweak-emacs/beginner-1-try-emacs-lisp.txt . If you're reading this lesson in Emacs, try putting your cursor after the closing =)= and calling =C-x C-e= (=eval-last-sexp=) on the following line: #+begin_src emacs-lisp (menu-bar-mode -1) #+end_src 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: #+begin_src emacs-lisp (menu-bar-mode 1) #+end_src As with =M-:= (=eval-expression=), you can use the =C-u= prefix to insert the results instead of displaying them. For example, try using =C-u C-x C-e= (=eval-last-sexp=) to evaluate the following expression: #+begin_src emacs-lisp (* 6 7) #+end_src ** If you want that code to run every time you start Emacs... ... *then* add it to your =~/.emacs.d/init.el= file. You can generally add new code at the end. If the code has something to do with =load-path=, it might be good to add it to the beginning instead. That way, your =load-path= changes can take effect before any libraries are loaded. Note: The Emacs configuration file used to be =~/.emacs=, and most webpages refer to that. =~/.emacs= still works - in fact, if you have that, it may stop Emacs from loading =~/.emacs.d/init.el=. On the other hand, if you use =~/.emacs.d/init.el= (and move your =~/.emacs= code to that file instead), then you have one less hidden file in your home directory (=~=). If you're adding code to your config and it's not getting loaded, make sure you have either =~/.emacs= or =~/.emacs.d/init.el=, but not both. 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. ** Practice Try this out: #+BEGIN_PRACTICE 1. Browse through http://www.emacswiki.org/emacs/CategoryDotEmacs 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 (sacha@sachachua.com). 2. Use =M-x ielm= to evaluate this expression interactively: #+begin_src emacs-lisp system-type #+end_src This shows you the value of the =system-type= variable. Note: Variables can be evaluated without the parentheses, but functions can't. Use You can use =ielm= to call functions like this, though: #+begin_src emacs-lisp (max 2 6 10 5) #+end_src 3. Use =M-:= (=eval-expression=) buffer to evaluate the following expression: #+begin_src emacs-lisp (* 21 2) #+end_src =M-:= is handy for quick calculations. Remember, you can use it with =C-u= (that is, =C-u M-:=) to *insert* the result into the buffer. Try it now: =C-u M-: (* 21 2)= 4. Use =C-x C-e= (=eval-last-sexp=) to evaluate the expression below. If you are reading this in Emacs, you can evaluate it by putting your cursor after the last =)= and calling =C-x C-e= (=eval-last-sexp=). If you are reading this outside Emacs, you can copy that text into any buffer and then use =C-x C-e= (=eval-last-sexp=) to evaluate it. #+begin_src emacs-lisp (* (+ 1 2) 3) #+end_src 5. Add =(message "Hello, world!")= to the end of your =~/.emacs.d/init.el= (or =~/.emacs=, if you're using that file instead). Use =M-x eval-buffer= 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. 6. Call =M-x visual-line-mode= to tell Emacs to visually wrap lines without actually changing the text. If you like this, add =(add-hook 'text-mode-hook 'turn-on-visual-line-mode)= to your =~/.emacs.d/init.el=. #+END_PRACTICE Next module: [[http://emacslife.com/read-lisp-tweak-emacs/beginner-2-understand-emacs-lisp.html]["How can I understand what Emacs Lisp code does?"]]