code.delx.au - gnu-emacs-elpa/blob - packages/yasnippet/doc/snippet-organization.org

   1 #+SETUPFILE: org-setup.inc
   2
   3 #+TITLE: Organizing snippets
   4
   5 * Basic structure
   6
   7    Snippet collections can be stored in plain text files. They are arranged by
   8    sub-directories naming *snippet tables*. These mostly name Emacs major names.
   9
  10    #+begin_example
  11    .
  12    |-- c-mode
  13    |   `-- printf
  14    |-- java-mode
  15    |   `-- println
  16    `-- text-mode
  17        |-- email
  18        `-- time
  19    #+end_example
  20
  21    The collections are loaded into *snippet tables* which the
  22    triggering mechanism (see [[file:snippet-expansion.org][Expanding Snippets]]) looks up and
  23    (hopefully) causes the right snippet to be expanded for you.
  24
  25 * Setting up =yas-snippet-dirs=
  26
  27    The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
  28    which collections to consider. It's used when you activate
  29    [[sym:yas-global-mode][=yas-global-mode=]] or call
  30    [[sym:yas-reload-all][=yas-reload-all=]] interactively.
  31
  32    The default considers:
  33
  34     - a personal collection that lives in =~/.emacs.d/snippets=
  35     - the bundled collection, taken as a relative path to =yasnippet.el= localtion
  36
  37    When you come across other snippet collections, do the following to try them
  38    out:
  39
  40    #+begin_src emacs-lisp :exports code
  41    ;; Develop in ~/emacs.d/mysnippets, but also
  42    ;; try out snippets in ~/Downloads/interesting-snippets
  43    (setq yas-snippet-dirs '("~/emacs.d/mysnippets"
  44                               "~/Downloads/interesting-snippets"))
  45
  46    ;; OR, keeping YASnippet defaults try out ~/Downloads/interesting-snippets
  47    (setq yas-snippet-dirs (append yas-snippet-dirs
  48                                   '("~/Downloads/interesting-snippets")))
  49    #+end_src
  50
  51    Collections appearing earlier in the list override snippets with same names
  52    appearing in collections later in the list. [[sym:yas-new-snippet][=yas-new-snippet=]] always stores
  53    snippets in the first collection.
  54
  55 * The =.yas-parents= file
  56
  57    It's very useful to have certain modes share snippets between
  58    themselves. To do this, choose a mode subdirectory and place a
  59    =.yas-parents= containing a whitespace-separated list of other mode
  60    names. When you reload those modes become parents of the original
  61    mode.
  62
  63    #+begin_example
  64    .
  65    |-- c-mode
  66    |   |-- .yas-parents    # contains "cc-mode text-mode"
  67    |   `-- printf
  68    |-- cc-mode
  69    |   |-- for
  70    |   `-- while
  71    |-- java-mode
  72    |   |-- .yas-parents    # contains "cc-mode text-mode"
  73    |   `-- println
  74    `-- text-mode
  75        |-- email
  76        `-- time
  77    #+end_example
  78
  79
  80 * TODO The =.yas-make-groups= file
  81
  82    If you place an empty plain text file =.yas-make-groups= inside one
  83    of the mode directories, the names of these sub-directories are
  84    considered groups of snippets and [[snippet-menu.org][the menu]] is organized much more
  85    cleanly:
  86
  87    [[./images/menu-groups.png]]
  88
  89    Another way to achieve this is to place a =# group:= directive
  90    inside the snippet definition. See [[./snippet-development.org][Writing Snippets]].
  91
  92    #+begin_example
  93    $ tree ruby-mode/
  94    ruby-mode/
  95    |-- .yas-make-groups
  96    |-- collections
  97    |   |-- each
  98    |   `-- ...
  99    |-- control structure
 100    |   |-- forin
 101    |   `-- ...
 102    |-- definitions
 103    |   `-- ...
 104    `-- general
 105       `-- ...
 106    #+end_example
 107
 108    Yet another way to create a nice snippet menu is to write into
 109    =.yas-make-groups= a menu definition. TODO
 110
 111 * The =.yas-setup.el= file
 112
 113   If there is file named =.yas-setup.el= in a mode's snippet
 114   subdirectory, it is loaded along with the snippets.  Utility
 115   functions used by the snippets can be put here.
 116
 117 * The =.yas-compiled-snippet.el= file
 118
 119    You may compile a top-level snippet directory with the
 120    =yas-compile-directory= function, which will create a
 121    =.yas-compiled-snippets.el= file under each mode subdirectory,
 122    which contains definitions for all snippets in the subdirectory.
 123    Compilation helps improve loading time.
 124
 125    Alternatively, you may compile all directories in the list
 126    =yas-snippet-dirs= with the =yas-recompile-all= function.
 127
 128 * The =.yas-skip= file
 129
 130   A =.yas-skip= file in a mode's snippet subdirectory tells YASnippet
 131   not to load snippets from there.