# Organizing snippets

- Intro and tutorial
- Howto: organize
- Howto: expand
- Howto: write
- Howto: menu
- FAQ
- ChangeLog
- Download

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
  - Nested organization
  - The `.yas-parents` file
  - The `.yas-make-groups` file
  - Using plain file names
- 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.