blob: 746cff00bb917eabce30d19a3acbaa1cfc2cbdc0 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
#+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
* The =.yas-setup.el= file
If there is file named =.yas-setup.el= in a mode's snippet
subdirectory, it is loaded along with the snippets. Utility
functions used by the snippets can be put here.
* 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.
* The =.yas-skip= file
A =.yas-skip= file in a mode's snippet subdirectory tells YASnippet
not to load snippets from there.
|
