forked from SirVer/ultisnips
/
UltiSnips-Quickstart.txt
218 lines (165 loc) · 8.04 KB
/
UltiSnips-Quickstart.txt
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
*UltiSnips-Quickstart.txt* For Vim version 7.0 or later.
The Ultimate Plugin for Snippets in Vim - forked version~
Please also have a look at README.rst which talks about why this fork
exists. Section 3 is most important
CONTENTS:
1. Contact / need help / bugs
2. Installation
3. SETUP / CONFIGURATION / how does this fork work ?
4. FAQ
10. More documentation
98a. Notes for snipmate(-snippets) users:
98b. Notes for UltiSnips users:
99. known bugs
999. links
==============================================================================
1. Contact / need help / bugs
bugs:
file against github.com/MarcWeber/ultisnips unless you're sure they also
happen on the [parent_ultisnips] project.
Then use [SirVer's bugtracker]
help:
If in trouble read documentation. If you still have trouble you can contact me
by irc (MarcWeber @ irc.freenode.net) or mail: marco-oweber@gmx.de.
Also See bugs at README.rst
==============================================================================
2. Installation
I don't care. I personally prefer vim-addon-manager (cause I wrote it for good
reasons), but all the other tools pathogen, vundle, .. should also get the job
done.
You may want to add the external snippet repository
github.com/honza/vim-snippets to runtimepath - then all snippets are
available
==============================================================================
3. SETUP / CONFIGURATION / how does this fork work ?
Which snippets are available ? ~
None by default. I recommend installing github.com/honza/vim-snippets
which contains snipmate snippets and a copy of SirVer's UltiSnips directory
or copying the UltiSnips directory from SirVer's repository. SirVer's
UltiSnips directory is upstream till he joins vim-snippets which I would
highly appreciate.
How does UltiSnips find snippets? ~
Rough reply: It knowsn about your snippets if you set &rtp to contain
the snippets and UltiSnips directories. Thus installing a plugin
such as github/honza/vim-snippets should be enough.
Then it depends on filetype and *_ft_filter settings which of those files get
loaded.
Eg when editing a filetype html you can tell UltiSnips to load
1) UltiSnips/html.snippets
2) UltiSnips/javascript.snippets
3) snipmate-snippets/javascript.snippets
in any runtimepath.
If you want to explore all details read the default VimL function
SnippetFilesForCurrentExpansionDefaultImplementation.
You can either provide your own function, or override the python function
calling the VimL function.
Snippet files are loaded as needed needed and reloaded automatically if their
file modification timestamp changes.
While loading snipmate snippets some errors may happen especially when
translating snipmate files.
Then quickfix is populated so that you can explore the cause fast (:cope).
For details See doc/UltiSnips.txt section "3.3 Snippet Search Path".
.vimrc setup ~
>
" declare global configuration dictionary so that config options can be added:
let g:UltiSnips = {}
" customize mappings, eg use snipmate like behaviour
" let g:UltiSnips.ExpandTrigger = "<tab>"
" " It does make sense to not use <tab> here, use UltiSnips default <c-j>
" " let g:UltiSnips.JumpForwardTrigger = "<tab>"
" let g:UltiSnips.JumpBackwardTrigger = "<c-k>"
" Now its time to tell UltiSnips about which snippets to load.
" You do so for snipmate snippets and UltiSnips snippets individually.
" This example illustrates a setup loading snipmate snippets.
" See plugin/UltiSnips.vim, it has much additional documentation.
" Assuming you're not overrding the default implemenation in the
" VimL function SnippetFilesForCurrentExpansionDefaultImplementation.
" == UltiSnips snippets ==
" Because I want to use the snipmate snippets 'default' does not load
" filetype.snippets snippet files.
" SirVer called the snippets to be present for all filetypes "all".
" So this fork follows his convention. Compare with _ which is used by
" snipmate but means the same.
"
" Now the default implementation reads &filetype, looks up the key in the
" dictionary and falls back to the default entry if there is no filetype
" specific entry.
"
" Thus if you're editing a cpp file ['cpp'] means that
" &rtp/UltiSnips/cpp.snippets and ..../all.snippets will be loaded if
" UltiSnips directory happens to be in your [._].vim directory only.
"
" For all other filetypes 'default' applies, which loads all.snippets
" from all &rtp/UltiSnips directories.
let g:UltiSnips.UltiSnips_ft_filter = {
\ 'default' : {'filetypes': ['all'] },
\ 'all' : {'filetypes': ['all'] },
\ 'cpp' : {'filetypes': ['cpp', 'all'], 'dir-regex': '[._]vim/UltiSnips$' },
\ }
" In the 'default' case the special word FILETYPE will be replaced by
" &filetype, thus ['all','FILETYPE'] will load &rtp/html.snippets if
" you're editing html files.
" choices could be nasty, never show them
let g:UltiSnips.always_use_first_snippet = 1
" == snipmate snippets ==
" _.snippets are meant to be snippets to be loaded always which is why
" they are contained in all cases
" This is pretty much the same as above:
" * For html, xhtml snipmate &rtp/snippets/javascript snippets get loaded
" * For cpp don't load any snipmate &rtp/snippets - because in this
" example UltiSnips snippets are preferred
let g:UltiSnips.snipmate_ft_filter = {
\ 'default' : {'filetypes': ["FILETYPE", "_"] },
\ 'html' : {'filetypes': ["html", "javascript", "_"] },
\ 'xhtml' : {'filetypes': ["xhtml", "html", "javascript", "_"] },
\ 'cpp' : {'filetypes': [] },
\ }
" Of course you want to adjust this to your own liking
==============================================================================
4. FAQ
What are (UltiSnips) snippets? ~
The native format, see 10.
What are snipmate-snippets? ~
Files having such a path: snippets/*.snippet
snippets start by "snippet", the snippet code is always prefixed by one <tab>,
leading <tab>s are replaced by indentation &sw when expanding.
UltiSnips snippets are more powerful, they allow "nested" placeholders and
such. See 10.
==============================================================================
10. More documentation
See doc/UltiSnips.txt
==============================================================================
98a. Notes for snipmate(-snippets) users:
UltiSnips now supports the same feature as snipmate: visually selecting
snippet text then hitting <cr> or running :RetabSnip will replace spaces by
<tab> characters. <tab> indicates "one indentation level" snipmate-snippets
files
_.snippets namespace (used always) is "all.snippets" namespace in UltiSnips.
You can still keep using "_" as seen above.
UltiSnips provides two different mappings for expand and jump to next
placeholder. This is because an expansion name might be the same as a var
name. So consider adopting to using two different mappings.
Also be aware that UltiSnips snippets are more powerful. Eg nested
placeholders are supported. See doc/UltiSnips.txt
==============================================================================
98b. Notes for UltiSnips users:
Please read the comments about how snippets are found and loaded carefully.
This changed.
See BUG [1]
==============================================================================
99. known bugs
BUG [1]:
The "extends foo" syntax causes errors. The fix is to
- delete it
- tell UltiSnips manually that eg zsh should load sh files as seen in
plugin/UltiSnips.vim
I'm sorry about this, probably this is "won't fix" because it would take too
much time.
- This fork does not tell YouCompleteMe about available snippets
If its very important to you help me fix it
There are probably more. Also see snipmate-merge-todo
==============================================================================
999. links
[parent_ultisnips]: See README.rst
[SirVer's bugtracker]: https://bugs.launchpad.net/ultisnips
vim:tw=78:ts=8:ft=help:norl: