diff options
Diffstat (limited to '')
| -rw-r--r-- | emacs.d/lisp/yasnippet/doc/snippet-organization.rst | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/emacs.d/lisp/yasnippet/doc/snippet-organization.rst b/emacs.d/lisp/yasnippet/doc/snippet-organization.rst new file mode 100644 index 0000000..dc7018c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-organization.rst @@ -0,0 +1,253 @@ +=================== +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 |