code.delx.au - gnu-emacs-elpa/blob - packages/yasnippet/doc/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 shadow 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 * TODO The =.yas-setup.el= file
 112
 113 ** TODO
 114
 115 * TODO The =.yas-compiled-snippet.el= file
 116
 117 ** TODO
 118
 119 * TODO The =.yas-skip= file
 120
 121 ** TODO