#+TITLE: Yet another snippet extension #+OPTIONS: toc:1 #+STARTUP: showall #+STYLE: # External links # #+LINK: smart-snippet http://code.google.com/p/smart-snippet #+LINK: pluskid http://pluskid.lifegoo.org #+LINK: screencast http://www.youtube.com/watch?v=ZCGmZK4V7Sg #+LINK: docs http://capitaomorte.github.com/yasnippet #+LINK: issues https://github.com/capitaomorte/yasnippet/issues #+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list #+LINK: forum http://groups.google.com/group/smart-snippet * Quick start *YASnippet* is a template system for Emacs. It allows you to type an abbreviation and automatically expand it into function templates. Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from TextMate's syntax, you can even [[#import-textmate][import most TextMate snippets]] YASnippet is an original creation of [[pluskid]] who also wrote its predecessor [[smart-snippet]]. ** Watch a demo [[youtube]] ** Installation Clone this repository somewhere #+begin_example $ cd ~/.emacs.d/plugins $ git clone https://github.com/capitaomorte/yasnippet #+end_example Add the following in your =.emacs= file: #+begin_src emacs-lisp :exports code (add-to-list 'load-path "~/.emacs.d/plugins/yasnippet") (require 'yasnippet) (yas/global-mode 1) #+end_src Add your own snippets to =~/.emacs.d/snippets= by placing files there or invoking [[#yas-new-snippet][=yas-new-snippet=]]. ** Import textmate snippets (rails example) :PROPERTIES: :CUSTOM_ID: import-textmate :END: YASnippet lets you use TextMate bundles directly: #+begin_example $ cd ~/.emacs.d/plugins $ git clone https://github.com/capitaomorte/yasnippet $ cd yasnippet $ git submodule init $ git submodule update $ gem install plist trollop $ rake convert_bundles # will convert ruby, rails and html bundles from drnic #+end_example Then, in your =.emacs= file #+begin_example (add-to-list 'load-path "~/.emacs.d/plugins/yasnippet") (require 'yasnippet) (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported")) (yas/global-mode 1) #+end_example Open some rails file (model, app, etc) and start using the textmate snippets. Consider that this is a work-in-progress and many snippets/commands might not work. Patches welcome! ** Contributing snippets Please *do not ask me* to add snippets to the default collection under =/snippets=. This collection is considered frozen. By customizing [[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good snippet collections out there. The =extras/textmate-import.rb= tool can import many actual Textmate snippets. I'm focusing on developing it and the accompanying =yas-setup.el= files that guide it with more difficult importations. The idea is to deprecate =/snippets= and replace it with =extras/imported=. ** Documentation, issues, etc Please refer to the comprehensive [[docs][documentation]] for full customization and support. If you think you've found a bug, please report it on [[issues][the GitHub issue tracker]]. (please **do not** submit new issues to the old [[googlecode-tracker][googlecode tracker]]) If you run into problems using YASnippet, or have snippets to contribute, post to the [[forum][yasnippet forum]]. Thank you very much for using YASnippet! * Organizing snippets ** Basic structure Snippet collections can be stored in plain text files. They are arranged by sub-directories naming *snippet tables*. These mostly name Emacs major names. #+begin_example . |-- c-mode | `-- printf |-- java-mode | `-- println `-- text-mode |-- email `-- time #+end_example The collections are loaded into *snippet tables* which the triggering mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and (hopefully) cause the right snippet to be expanded for you. ** Setting up =yas-snippet-dirs= The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet which collections to consider. It's used when you activate [[#yas-global-mode][=yas-global-mode=]] or call [[#yas-reload-all][=yas-reload-all=]] interactively. The default considers: - a personal collection that lives in =~/.emacs.d/snippets= - the bundled collection, taken as a relative path to =yasnippet.el= localtion When you come across other snippet collections, do the following to try them out: #+begin_src emacs-lisp :exports code ;; Develop in ~/emacs.d/mysnippets, but also ;; try out snippets in ~/Downloads/interesting-snippets (setq yas/snippet-dirs '("~/emacs.d/mysnippets" "~/Downloads/interesting-snippets")) ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets (setq yas/snippet-dirs (append yas/snippet-dirs '("~/Downloads/interesting-snippets"))) #+end_src Collections appearing earlier in the list shadow snippets with same names appearing in collections later in the list. [[#yas-new-snippet][=yas-new-snippet=]] always stores snippets in the first collection. ** The =.yas.parents= file It's very useful to have certain modes share snippets between themselves. To do this, choose a mode subdirectory and place a =.yas-parents= containing a whitespace-separated list of other mode names. When you reload those modes become parents of the original mode. #+begin_example . |-- c-mode | |-- .yas-parents # contains "cc-mode text-mode" | `-- printf |-- cc-mode | |-- for | `-- while |-- java-mode | |-- .yas-parents # contains "cc-mode text-mode" | `-- println `-- text-mode |-- email `-- time #+end_example ** TODO The =.yas-make-groups= file If you place an empty plain text file =.yas-make-groups= inside one of the mode directories, the names of these sub-directories are considered groups of snippets and [[snippet-menu][the menu]] is organized much more cleanly: (TODO image) Another alternative way to achieve this is to place a =# group:= directive inside the snippet definition. See [[#writing-snippets][Writing Snippets]] #+begin_example $ tree ruby-mode/ ruby-mode/ |-- .yas-make-groups |-- collections | |-- each | `-- ... |-- control structure | |-- forin | `-- ... |-- definitions | `-- ... `-- general `-- ... #+end_example Yet another way to create a nice snippet menu is to write into =.yas-make-groups= a menu definition. TODO ** TODO The =.yas-setup.el= file *** TODO ** TODO The =.yas-compiled-snippet.el= file *** TODO ** The =.yas-skip= file * Expanding Snippets :PROPERTIES: :CUSTOM_ID: expand-snippets :END: This section describes how YASnippet chooses snippets for expansion at point. Maybe, you'll want some snippets to be expanded in a particular mode, or only under certain conditions, or be prompted using ** Triggering expansion To make a snippet expand after the cursor: * Type an the snippet's *trigger key* then press the key defined in [[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB"). * Use the snippet's *keybinding*. * Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet== or its keybinding =C-c & C-s=). * By expanding directly from the "YASnippet" menu in the menu-bar * Using hippie-expand * Use m2m's excellent auto-complete * Reference #+BEGIN_SRC emacs-lisp :exports results :results value raw (yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form) `("Customization variables" . ,#'(lambda (sym) (and (boundp sym) (get sym 'standard-value)))) `("Useful functions" . ,#'fboundp) `("Useful variables" . ,#'boundp)) #+END_SRC # Local Variables: # mode: org # fill-column: 80 # coding: utf-8 # End: