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

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