===================
Organizing snippets
===================
.. _Organizing Snippets: snippet-organization.html
.. _Expanding Snippets: snippet-expansion.html
.. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
.. contents::
Loading snippets
================
Snippet definitions are stored in files in the filesystem. Unless you
use the simpler `bundle version <index.html@installation>`_), 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``:
.. sourcecode:: common-lisp
;; 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:
.. sourcecode:: common-lisp
;; 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:
.. sourcecode:: text
$ 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``.
.. image:: images/menu-parent.png
:align: right
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.
.. sourcecode:: text
$ 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
-----------------------------
.. image:: images/menu-groups.png
:align: right
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`_.
.. sourcecode:: text
$ 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.
.. sourcecode:: text
$ 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.
.. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl
.. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el
.. LocalWords: rjs RET
