+ +

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

Contents

Loading snippets
Organizing snippets
+
YASnippet bundle
Customizable variables
- yas/root-directory
- yas/ignore-filenames-as-triggers
+

Loading snippets

Snippet definitions are stored in files in the filesystem. Unless you +use the simpler bundle version), these +are arranged so that YASnippet can load them into snippet +tables. The triggering mechanisms (see Expanding snippets) will +look up these snippet tables and (hopefully) expand the snippet you +intended.

The non-bundle version of YASnippet, once unpacked, comes with a full +directory of snippets, which you can copy somewhere and use. You can +also create or download more directories.

Once these directories are in place reference them in the variable +yas/root-directory and load them with yas/load-directory:

;; Develop and keep personal snippets under ~/emacs.d/mysnippets
+(setq yas/root-directory "~/emacs.d/mysnippets")
+
+;; Load the snippets
+(yas/load-directory yas/root-directory)
+

The point in using yas/root-directory (as opposed to calling +yas/load-directory directly) is considering "~/emacs.d/mysnippets" +for snippet development, so you can use commands like +yas/new-snippet and others described in section Writing +Snippets.

You can make this variable a list and store more items into it:

;; Develop in ~/emacs.d/mysnippets, but also
+;; try out snippets in ~/Downloads/interesting-snippets
+(setq yas/root-directory '("~/emacs.d/mysnippets"
+                           "~/Downloads/interesting-snippets"))
+
+;; Map `yas/load-directory' to every element
+(mapc 'yas/load-directory yas/root-directory)
+

In this last example, the all the directories are loaded and their +snippets considered for expansion. However development still happens +in the first element, "~/emacs.d/mysnippets".

Organizing snippets

Once you've setup yas/root-directory , you can store snippets +inside sub-directories of these directories.

Snippet definitions are put in plain text files. They are arranged by +sub-directories, and the snippet tables are named after these directories.

The name corresponds to the Emacs mode where you want expansion to +take place. For example, snippets for c-mode are put in the +c-mode sub-directory. You can also skip snippet storage altogether +and use the bundle (see YASnippet bundle).

Nested organization

Here is an excerpt of a directory hierarchy containing snippets +for some modes:

$ tree
+.
+`-- text-mode
+    |-- cc-mode
+    |   |-- c-mode
+    |   |   `-- printf
+    |   |-- for
+    |   |-- java-mode
+    |   |   `-- println
+    |   `-- while
+    |-- email
+    |-- perl-mode
+    |   |-- cperl-mode
+    |   `-- for
+    `-- time
+

A parent directory acts as a parent table of any of its +sub-directories. This is one of the ways different Emacs major modes +can share snippet definitions. As you can see above, c-mode and +java-mode share the same parent cc-mode and its while +snipepts, while all modes are share the time snippet from +text-mode.

This can be also used to as an alias -- cperl-mode is an empty +directory whose parent is perl-mode.

The `.yas-parents` file

An alternate (and preferred) way of setting up parent tables consists +of placing a plain text file .yas-parents inside one of the +sub-directories. By doing this, you avoid complex directory +nesting. In the .yas-parents file you just write +whitespace-separated names of modes. This allows more flexibility and +readability of your snippet hierarchy.

$ tree
+.
+|-- 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
+

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 The YASnippet Menu is organized +much more cleanly, as you can see in the image.

Another alternative way to achieve this is to place a # group: +directive inside the snippet definition. See Writing Snippets.

$ tree ruby-mode/
+ruby-mode/
+|-- .yas-make-groups
+|-- collections
+|   |-- each
+|   `-- ...
+|-- control structure
+|   |-- forin
+|   `-- ...
+|-- definitions
+|   `-- ...
+`-- general
+    `-- ...
+

Using plain file names

Normally, file names act as the snippet expansion abbreviation (also +known as the snippet key or snippet trigger, see Expanding +Snippets).

However, if you customize the variable +yas/ignore-filenames-as-triggers to be true or place an empty +file .yas-ignore-filename-triggers you can use much more +descriptive file names. This is useful if many snippets within a mode +share the same trigger key.

$ tree rails-mode/
+rails-mode/
+|-- .yas-make-groups
+|-- .yas-ignore-filename-triggers
+|-- Insert ERb's <% __ %> or <%= __ %>.yasnippet
+|-- asserts
+|   |-- assert(var = assigns(%3Avar)).yasnippet
+|   |-- assert_difference.yasnippet
+|   |-- assert_no_difference.yasnippet
+|   |-- assert_redirected_to (nested path plural).yasnippet
+|   |-- assert_redirected_to (nested path).yasnippet
+|   |-- assert_redirected_to (path plural).yasnippet
+|   |-- assert_redirected_to (path).yasnippet
+|   |-- assert_rjs.yasnippet
+|   `-- assert_select.yasnippet
+

YASnippet bundle

The most convenient way to define snippets for YASnippet is to put +them in a directory arranged by the mode and use +yas/load-directory to load them.

However, this might slow down the Emacs start-up speed if you have many +snippets. You can use yas/define-snippets to define a bunch of +snippets for a particular mode in an Emacs-lisp file.

Since this is hard to maintain, there's a better way: define your +snippets in directory and then call M-x yas/compile-bundle to +compile it into a bundle file when you modified your snippets.

The release bundle of YASnippet is produced by +yas/compile-bundle. The bundle uses yas/define-snippets to +define snippets. This avoids the IO and parsing overhead when loading +snippets.

Further more, the generated bundle is a stand-alone file not depending +on yasnippet.el. The released bundles of YASnippet are all +generated this way.

See the internal documentation for these functions

M-x describe-function RET yas/define-snippets RET
M-x describe-function RET yas/compile-bundle RET.

Customizable variables

`yas/root-directory`

Root directory that stores the snippets for each major mode.

If you set this from your .emacs, can also be a list of strings, +for multiple root directories. If you make this a list, the first +element is always the user-created snippets directory. Other +directories are used for bulk reloading of all snippets using +yas/reload-all

`yas/ignore-filenames-as-triggers`

If non-nil, don't derive tab triggers from filenames.

This means a snippet without a # key: directive wont have a tab +trigger.

+ + + +

+ + +