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

   1 * Organizing snippets
   2
   3 ** Loading snippets
   4
   5 Snippet definitions are stored in files in the filesystem. Unless you
   6 use the simpler [[index.html@installation][bundle version]]), these are
   7 arranged so that YASnippet can load them into /snippet tables/. The
   8 triggering mechanisms (see [[snippet-expansion.html][Expanding
   9 snippets]]) will look up these snippet tables and (hopefully) expand the
  10 snippet you intended.
  11
  12 The non-bundle version of YASnippet, once unpacked, comes with a full
  13 directory of snippets, which you can copy somewhere and use. You can
  14 also create or download more directories.
  15
  16 Once these directories are in place reference them in the variable
  17 =yas-root-directory= and load them with =yas-load-directory=:
  18
  19 The point in using =yas-root-directory= (as opposed to calling
  20 =yas-load-directory= directly) is considering "~/emacs.d/mysnippets" for
  21 snippet development, so you can use commands like =yas-new-snippet= and
  22 others described in section [[snippet-development.html][Writing
  23 Snippets]].
  24
  25 You can make this variable a list and store more items into it:
  26
  27 In this last example, the all the directories are loaded and their
  28 snippets considered for expansion. However development still happens in
  29 the first element, "~/emacs.d/mysnippets".
  30
  31 ** Organizing snippets
  32
  33 Once you've setup =yas-root-directory= , you can store snippets inside
  34 sub-directories of these directories.
  35
  36 Snippet definitions are put in plain text files. They are arranged by
  37 sub-directories, and the snippet tables are named after these
  38 directories.
  39
  40 The name corresponds to the Emacs mode where you want expansion to take
  41 place. For example, snippets for =c-mode= are put in the =c-mode=
  42 sub-directory.
  43
  44 *** The =.yas.parents= file
  45
  46 It's very useful to have certain modes share snippets between
  47 themselves. To do this, choose a mode subdirectory and place a
  48 =.yas-parents= containing a whitespace-separated list of other mode
  49 names. When you reload those modes become parents of the original mode.
  50
  51 *** The =.yas-make-groups= file
  52
  53 [[images/menu-groups.png]]
  54
  55 If you place an empty plain text file =.yas-make-groups= inside one of
  56 the mode directories, the names of these sub-directories are considered
  57 groups of snippets and [[snippet-menu.html][The YASnippet Menu]] is
  58 organized much more cleanly, as you can see in the image.
  59
  60 Another alternative way to achieve this is to place a =# group:=
  61 directive inside the snippet definition. See
  62 [[snippet-development.html][Writing Snippets]].
  63
  64 ** YASnippet bundle
  65
  66 The most convenient way to define snippets for YASnippet is to put them
  67 in a directory arranged by the mode and use =yas-load-directory= to load
  68 them.
  69
  70 However, this might slow down the Emacs start-up speed if you have many
  71 snippets. You can use =yas-define-snippets= to define a bunch of
  72 snippets for a particular mode in an Emacs-lisp file.
  73
  74 Since this is hard to maintain, there's a better way: define your
  75 snippets in directory and then call =M-x yas-compile-bundle= to compile
  76 it into a bundle file when you modified your snippets.
  77
  78 The release bundle of YASnippet is produced by =yas-compile-bundle=. The
  79 bundle uses =yas-define-snippets= to define snippets. This avoids the IO
  80 and parsing overhead when loading snippets.
  81
  82 Further more, the generated bundle is a stand-alone file not depending
  83 on =yasnippet.el=. The released bundles of YASnippet are all generated
  84 this way.
  85
  86 See the internal documentation for these functions
  87
  88 -  =M-x describe-function RET yas-define-snippets RET=
  89 -  =M-x describe-function RET yas-compile-bundle RET=.
  90
  91 ** Customizable variables
  92
  93 *** =yas-root-directory=
  94
  95 Root directory that stores the snippets for each major mode.
  96
  97 If you set this from your .emacs, can also be a list of strings, for
  98 multiple root directories. If you make this a list, the first element is
  99 always the user-created snippets directory. Other directories are used
 100 for bulk reloading of all snippets using =yas-reload-all=
 101
 102 *** =yas-ignore-filenames-as-triggers=
 103
 104 If non-nil, don't derive tab triggers from filenames.
 105
 106 This means a snippet without a =# key:= directive wont have a tab
 107 trigger.