4 *YASnippet* is a template system for Emacs. It allows you to type an
5 abbreviation and automatically expand it into function templates. Bundled
6 language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML,
7 CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
8 even [import most TextMate snippets](#import-textmate)
10 YASnippet is an original creation of [pluskid][pluskid] who also wrote its predecessor
11 [smart-snippet][smart-snippet].
16 Do so on [youtube][youtube]
21 Clone this repository somewhere
23 $ cd ~/.emacs.d/plugins
24 $ git clone https://github.com/capitaomorte/yasnippet
26 Add the following in your =.emacs= file:
28 (add-to-list 'load-path
29 "~/.emacs.d/plugins/yasnippet")
33 Add your own snippets to `~/.emacs.d/snippets` by placing files there or
34 invoking `yas-new-snippet`.
36 Import textmate snippets (rails example)
37 ----------------------------------------
39 YASnippet lets you use TextMate bundles directly:
41 $ cd ~/.emacs.d/plugins
42 $ git clone https://github.com/capitaomorte/yasnippet
45 $ git submodule update
46 $ gem install plist trollop
47 $ rake convert_bundles # will convert ruby, rails and html bundles from drnic
49 Then, in your `.emacs` file
52 (add-to-list 'load-path
53 "~/.emacs.d/plugins/yasnippet")
55 (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
58 Open some rails file (model, app, etc) and start using the textmate
59 snippets. Consider that this is a work-in-progress and many snippets/commands
60 might not work. Patches welcome!
65 Please *do not ask me* to add snippets to the default collection under
66 `/snippets`. This collection is considered frozen. By customizing
67 `yas-snippet-dirs` you can point yasnippet to good snippet collections out
70 The `extras/textmate-import.rb` tool can import many actual Textmate snippets.
71 I'm focusing on developing it and the accompanying `yas-setup.el` files that
72 guide it with more difficult importations. The idea is to deprecate `/snippets=
73 and replace it with =extras/imported`.
75 Documentation, issues, etc
76 --------------------------
78 Please refer to the comprehensive [documentation](docs) for full
79 customization and support. If you think you've found a bug, please report it
80 on [the GitHub issue tracker](issues). (please **do not** submit new
81 issues to the old [googlecode tracker](googlecode-tracker))
83 If you run into problems using YASnippet, or have snippets to contribute,
84 post to the [yasnippet forum](forum). Thank you very much for using
93 Snippet collections can be stored in plain text files. They are arranged by
94 sub-directories naming *snippet tables*. These mostly name Emacs major names.
105 The collections are loaded into *snippet tables* which the triggering
106 mechanism (see [Expanding snippets](#expand-snippets)) looks up and
107 (hopefully) cause the right snippet to be expanded for you.
109 Setting up `yas-snippet-dirs`
110 -----------------------------
112 The emacs variable `yas-snippet-dirs` tells YASnippet
113 which collections to consider. It's used when you activate
114 `yas-global-mode` or call
115 `yas-reload-all` interactively.
117 The default considers:
119 - a personal collection that lives in `~/.emacs.d/snippets`
120 - the bundled collection, taken as a relative path to `yasnippet.el` localtion
122 When you come across other snippet collections, do the following to try them
125 ;; Develop in ~/emacs.d/mysnippets, but also
126 ;; try out snippets in ~/Downloads/interesting-snippets
127 (setq yas/snippet-dirs '("~/emacs.d/mysnippets"
128 "~/Downloads/interesting-snippets"))
130 ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
131 (setq yas/snippet-dirs (append yas/snippet-dirs
132 '("~/Downloads/interesting-snippets")))
134 Collections appearing earlier in the list shadow snippets with same names
135 appearing in collections later in the list. `yas-new-snippet` always stores
136 snippets in the first collection.
138 The `.yas.parents` file
139 -----------------------
141 It's very useful to have certain modes share snippets between themselves. To do
142 this, choose a mode subdirectory and place a `.yas-parents` containing a
143 whitespace-separated list of other mode names. When you reload those modes
144 become parents of the original mode.
148 | |-- .yas-parents # contains "cc-mode text-mode"
154 | |-- .yas-parents # contains "cc-mode text-mode"
160 The `.yas-make-groups` file
161 ---------------------------
163 If you place an empty plain text file `.yas-make-groups` inside one of the mode
164 directories, the names of these sub-directories are considered groups of
165 snippets and [the menu](snippet-menu) is organized much more cleanly:
169 Another alternative way to achieve this is to place a `# group:` directive
170 inside the snippet definition. See [Writing Snippets](#writing-snippets)
179 |-- control structure
188 Yet another way to create a nice snippet menu is to write into
189 `.yas-make-groups` a menu definition. TODO
191 TODO The `.yas-setup.el` file
192 -----------------------------
196 TODO The `.yas-compiled-snippet.el` file
197 ----------------------------------------
207 This section describes how YASnippet chooses snippets for expansion at point.
209 Maybe, you'll want some snippets to be expanded in a particular
210 mode, or only under certain conditions, or be prompted using
215 To make a snippet expand after the cursor:
217 * Type an the snippet's *trigger key* then press the key defined in
220 * Use the snippet's *keybinding*.
222 * Call [`yas-insert-snippet=](#yas-insert-snippet) (use `M-x
223 yas-insert-snippet`= or its keybinding =C-c & C-s`).
225 * By expanding directly from the "YASnippet" menu in the menu-bar
227 * Using hippie-expand
229 * Use m2m's excellent [auto-complete](http://github.com/m2m/autocomplete)
234 (yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
235 `("Customization variables" . ,#'(lambda (sym)
237 (get sym 'standard-value))))
238 `("Useful functions" . ,#'fboundp)
239 `("Useful variables" . ,#'boundp))
241 [smart-snippet]: http://code.google.com/p/smart-snippet
242 [pluskid]: http://pluskid.lifegoo.org
243 [screencast]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
244 [docs]: http://capitaomorte.github.com/yasnippet
245 [issues]: https://github.com/capitaomorte/yasnippet/issues
246 [googlecode-tracker]: http://code.google.com/p/yasnippet/issues/list
247 [forum]: http://groups.google.com/group/smart-snippet