yasnippet/doc/snippet-organization.org

Organizing snippets

• Basic structure
• Setting up yas-snippet-dirs
• The .yas-parents file
• The .yas-make-groups file
• The .yas-setup.el file
  • TODO
• The .yas-compiled-snippet.el file
• The .yas-skip file
  • TODO

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.

.
|-- c-mode
|   `-- printf
|-- java-mode
|   `-- println
`-- text-mode
    |-- email
    `-- time

The collections are loaded into snippet tables which the triggering mechanism (see Expanding Snippets) looks up and (hopefully) causes the right snippet to be expanded for you.

Setting up yas-snippet-dirs

The emacs variable yas-snippet-dirs tells YASnippet which collections to consider. It's used when you activate yas-global-mode or call 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:

;; 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 defaults try out ~/Downloads/interesting-snippets
(setq yas-snippet-dirs (append yas-snippet-dirs
                               '("~/Downloads/interesting-snippets")))

Collections appearing earlier in the list override snippets with same names appearing in collections later in the list. 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.

.
|-- 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

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 the menu is organized much more cleanly:

Another 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
   `-- ...

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

The .yas-compiled-snippet.el file

You may compile a top-level snippet directory with the yas-compile-directory function, which will create a .yas-compiled-snippets.el file under each mode subdirectory, which contains definitions for all snippets in the subdirectory. Compilation helps improve loading time.

Alternatively, you may compile all directories in the list yas-snippet-dirs with the yas-recompile-all function.

TODO The .yas-skip file

TODO