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

   1 ===================
   2 Organizing snippets
   3 ===================
   4
   5 .. _Organizing Snippets: snippet-organization.html
   6 .. _Expanding Snippets: snippet-expansion.html
   7 .. _Writing Snippets: snippet-development.html
   8 .. _The YASnippet Menu: snippet-menu.html
   9
  10 .. contents::
  11
  12 Loading snippets
  13 ================
  14
  15 Snippet definitions are stored in files in the filesystem. Unless you
  16 use the simpler `bundle version <index.html@installation>`_), these
  17 are arranged so that YASnippet can load them into *snippet
  18 tables*. The triggering mechanisms (see `Expanding snippets`_) will
  19 look up these snippet tables and (hopefully) expand the snippet you
  20 intended.
  21
  22 The non-bundle version of YASnippet, once unpacked, comes with a full
  23 directory of snippets, which you can copy somewhere and use. You can
  24 also create or download more directories.
  25
  26 Once these directories are in place reference them in the variable
  27 ``yas/root-directory`` and load them with ``yas/load-directory``:
  28
  29 .. sourcecode:: common-lisp
  30
  31   ;; Develop and keep personal snippets under ~/emacs.d/mysnippets
  32   (setq yas/root-directory "~/emacs.d/mysnippets")
  33
  34   ;; Load the snippets
  35   (yas/load-directory yas/root-directory)
  36
  37 The point in using ``yas/root-directory`` (as opposed to calling
  38 ``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets"
  39 for snippet development, so you can use commands like
  40 ``yas/new-snippet`` and others described in section `Writing
  41 Snippets`_.
  42
  43 You can make this variable a list and store more items into it:
  44
  45 .. sourcecode:: common-lisp
  46
  47   ;; Develop in ~/emacs.d/mysnippets, but also
  48   ;; try out snippets in ~/Downloads/interesting-snippets
  49   (setq yas/root-directory '("~/emacs.d/mysnippets"
  50                              "~/Downloads/interesting-snippets"))
  51
  52   ;; Map `yas/load-directory' to every element
  53   (mapc 'yas/load-directory yas/root-directory)
  54
  55 In this last example, the all the directories are loaded and their
  56 snippets considered for expansion. However development still happens
  57 in the first element, "~/emacs.d/mysnippets".
  58
  59 Organizing snippets
  60 ===================
  61
  62 Once you've setup ``yas/root-directory`` , you can store snippets
  63 inside sub-directories of these directories.
  64
  65 Snippet definitions are put in plain text files. They are arranged
  66 by sub-directories, and the snippet tables are named after these
  67 directories.
  68
  69 The name corresponds to the Emacs mode where you want expansion to
  70 take place. For example, snippets for ``c-mode`` are put in the
  71 ``c-mode`` sub-directory.
  72
  73 The ``.yas.parents`` file
  74 -------------------------
  75
  76 It's very useful to have certain modes share snippets between
  77 themselves. To do this, choose a mode subdirectory and place a
  78 ``.yas-parents`` containing a whitespace-separated list of other
  79 mode names. When you reload those modes become parents of the
  80 original mode.
  81
  82 .. sourcecode:: text
  83
  84   $ tree
  85   .
  86   |-- c-mode
  87   |   |-- .yas-parents    # contains "cc-mode text-mode"
  88   |   `-- printf
  89   |-- cc-mode
  90   |   |-- for
  91   |   `-- while
  92   |-- java-mode
  93   |   |-- .yas-parents    # contains "cc-mode text-mode"
  94   |   `-- println
  95   `-- text-mode
  96       |-- email
  97       `-- time
  98
  99 The ``.yas-make-groups`` file
 100 -----------------------------
 101
 102 .. image:: images/menu-groups.png
 103    :align: right
 104
 105 If you place an empty plain text file ``.yas-make-groups`` inside one
 106 of the mode directories, the names of these sub-directories are
 107 considered groups of snippets and `The YASnippet Menu`_ is organized
 108 much more cleanly, as you can see in the image.
 109
 110 Another alternative way to achieve this is to place a ``# group:``
 111 directive inside the snippet definition. See `Writing Snippets`_.
 112
 113 .. sourcecode:: text
 114
 115   $ tree ruby-mode/
 116   ruby-mode/
 117   |-- .yas-make-groups
 118   |-- collections
 119   |   |-- each
 120   |   `-- ...
 121   |-- control structure
 122   |   |-- forin
 123   |   `-- ...
 124   |-- definitions
 125   |   `-- ...
 126   `-- general
 127       `-- ...
 128
 129
 130 YASnippet bundle
 131 ================
 132
 133 The most convenient way to define snippets for YASnippet is to put
 134 them in a directory arranged by the mode and use
 135 ``yas/load-directory`` to load them.
 136
 137 However, this might slow down the Emacs start-up speed if you have many
 138 snippets. You can use ``yas/define-snippets`` to define a bunch of
 139 snippets for a particular mode in an Emacs-lisp file.
 140
 141 Since this is hard to maintain, there's a better way: define your
 142 snippets in directory and then call ``M-x yas/compile-bundle`` to
 143 compile it into a bundle file when you modified your snippets.
 144
 145 The release bundle of YASnippet is produced by
 146 ``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to
 147 define snippets. This avoids the IO and parsing overhead when loading
 148 snippets.
 149
 150 Further more, the generated bundle is a stand-alone file not depending
 151 on ``yasnippet.el``. The released bundles of YASnippet are all
 152 generated this way.
 153
 154 See the internal documentation for these functions
 155
 156 * ``M-x describe-function RET yas/define-snippets RET``
 157 * ``M-x describe-function RET yas/compile-bundle RET``.
 158
 159 Customizable variables
 160 ======================
 161
 162 ``yas/root-directory``
 163 ----------------------
 164
 165 Root directory that stores the snippets for each major mode.
 166
 167 If you set this from your .emacs, can also be a list of strings,
 168 for multiple root directories. If you make this a list, the first
 169 element is always the user-created snippets directory. Other
 170 directories are used for bulk reloading of all snippets using
 171 ``yas/reload-all``
 172
 173 ``yas/ignore-filenames-as-triggers``
 174 ------------------------------------
 175
 176 If non-nil, don't derive tab triggers from filenames.
 177
 178 This means a snippet without a ``# key:`` directive wont have a tab
 179 trigger.
 180
 181 ..  LocalWords:  html YASnippet filesystem yas sourcecode setq mapc printf perl
 182 ..  LocalWords:  println cperl forin filenames filename ERb's yasnippet Avar el
 183 ..  LocalWords:  rjs RET