mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
0ada0fc944
Specifically, fill in the section about .yas-compiled-snippet.el, which was previously labelled as TODO. * doc/snippet-organization.org (The =.yas-compiled-snippet.el= file): Fill in section.
137 lines
4.2 KiB
Org Mode
137 lines
4.2 KiB
Org Mode
#+SETUPFILE: org-setup.inc
|
|
|
|
#+TITLE: Organizing snippets
|
|
|
|
* Basic structure
|
|
|
|
Snippet collections can be stored in plain text files. They are arranged by
|
|
sub-directories naming *snippet tables*. These mostly name Emacs major names.
|
|
|
|
#+begin_example
|
|
.
|
|
|-- c-mode
|
|
| `-- printf
|
|
|-- java-mode
|
|
| `-- println
|
|
`-- text-mode
|
|
|-- email
|
|
`-- time
|
|
#+end_example
|
|
|
|
The collections are loaded into *snippet tables* which the
|
|
triggering mechanism (see [[file:snippet-expansion.org][Expanding Snippets]]) looks up and
|
|
(hopefully) causes the right snippet to be expanded for you.
|
|
|
|
* Setting up =yas-snippet-dirs=
|
|
|
|
The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
|
|
which collections to consider. It's used when you activate
|
|
[[sym:yas-global-mode][=yas-global-mode=]] or call
|
|
[[sym:yas-reload-all][=yas-reload-all=]] interactively.
|
|
|
|
The default considers:
|
|
|
|
- a personal collection that lives in =~/.emacs.d/snippets=
|
|
- the bundled collection, taken as a relative path to =yasnippet.el= localtion
|
|
|
|
When you come across other snippet collections, do the following to try them
|
|
out:
|
|
|
|
#+begin_src emacs-lisp :exports code
|
|
;; Develop in ~/emacs.d/mysnippets, but also
|
|
;; try out snippets in ~/Downloads/interesting-snippets
|
|
(setq yas-snippet-dirs '("~/emacs.d/mysnippets"
|
|
"~/Downloads/interesting-snippets"))
|
|
|
|
;; OR, keeping YASnippet defaults try out ~/Downloads/interesting-snippets
|
|
(setq yas-snippet-dirs (append yas-snippet-dirs
|
|
'("~/Downloads/interesting-snippets")))
|
|
#+end_src
|
|
|
|
Collections appearing earlier in the list override snippets with same names
|
|
appearing in collections later in the list. [[sym:yas-new-snippet][=yas-new-snippet=]] always stores
|
|
snippets in the first collection.
|
|
|
|
* The =.yas-parents= file
|
|
|
|
It's very useful to have certain modes share snippets between
|
|
themselves. To do this, choose a mode subdirectory and place a
|
|
=.yas-parents= containing a whitespace-separated list of other mode
|
|
names. When you reload those modes become parents of the original
|
|
mode.
|
|
|
|
#+begin_example
|
|
.
|
|
|-- c-mode
|
|
| |-- .yas-parents # contains "cc-mode text-mode"
|
|
| `-- printf
|
|
|-- cc-mode
|
|
| |-- for
|
|
| `-- while
|
|
|-- java-mode
|
|
| |-- .yas-parents # contains "cc-mode text-mode"
|
|
| `-- println
|
|
`-- text-mode
|
|
|-- email
|
|
`-- time
|
|
#+end_example
|
|
|
|
|
|
* TODO The =.yas-make-groups= file
|
|
|
|
If you place an empty plain text file =.yas-make-groups= inside one
|
|
of the mode directories, the names of these sub-directories are
|
|
considered groups of snippets and [[snippet-menu.org][the menu]] is organized much more
|
|
cleanly:
|
|
|
|
[[./images/menu-groups.png]]
|
|
|
|
Another way to achieve this is to place a =# group:= directive
|
|
inside the snippet definition. See [[./snippet-development.org][Writing Snippets]].
|
|
|
|
#+begin_example
|
|
$ tree ruby-mode/
|
|
ruby-mode/
|
|
|-- .yas-make-groups
|
|
|-- collections
|
|
| |-- each
|
|
| `-- ...
|
|
|-- control structure
|
|
| |-- forin
|
|
| `-- ...
|
|
|-- definitions
|
|
| `-- ...
|
|
`-- general
|
|
`-- ...
|
|
#+end_example
|
|
|
|
Yet another way to create a nice snippet menu is to write into
|
|
=.yas-make-groups= a menu definition. TODO
|
|
|
|
* TODO The =.yas-setup.el= file
|
|
|
|
** TODO
|
|
|
|
* The =.yas-compiled-snippet.el= file
|
|
|
|
You may compile a top-level snippet directory with the
|
|
=yas-compile-directory= function, which will create a
|
|
=.yas-compiled-snippets.el= file under each mode subdirectory,
|
|
which contains definitions for all snippets in the subdirectory.
|
|
Compilation helps improve loading time.
|
|
|
|
Alternatively, you may compile all directories in the list
|
|
=yas-snippet-dirs= with the =yas-recompile-all= function.
|
|
|
|
*Caveat.* At the moment, when you try to use the
|
|
=yas-visit-snippet-file= function to edit a compiled snippet loaded
|
|
from a =.yas-compiled-snippets.el= file, the content of the snippet
|
|
will be opened in a buffer, but it might not be a verbatim copy of
|
|
your original snippet, and =yas-load-snippet-buffer-and-close=
|
|
won't offer to save to the original snippet file. See
|
|
[[https://github.com/capitaomorte/yasnippet/issues/597][#597]].
|
|
|
|
* TODO The =.yas-skip= file
|
|
|
|
** TODO
|