Organizing snippets

Table of Contents

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 mode 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:

menu-groups.png

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

The .yas-setup.el file

If there is file named .yas-setup.el in a mode's snippet subdirectory, it is loaded along with the snippets. Utility functions used by the snippets can be put here.

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.

The .yas-skip file

A .yas-skip file in a mode's snippet subdirectory tells YASnippet not to load snippets from there.


Generated by Emacs 26.1 (Org mode 9.1.9) from 0.13.0 (2018-05-13 16:12:51)

Validate