-
-
Notifications
You must be signed in to change notification settings - Fork 688
/
UltiSnips.txt
1875 lines (1458 loc) · 75.2 KB
/
UltiSnips.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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*UltiSnips.txt* For Vim version 7.0 or later.
The Ultimate Plugin for Snippets in Vim~
UltiSnips *snippet* *snippets* *UltiSnips*
1. Description |UltiSnips-description|
1.1 Requirements |UltiSnips-requirements|
1.2 Acknowledgments |UltiSnips-acknowledgments|
2. Installation and Updating |UltiSnips-installnupdate|
3. Settings & Commands |UltiSnips-settings|
3.1 Commands |UltiSnips-commands|
3.2 Triggers |UltiSnips-triggers|
3.2.1 Using your own trigger functions |UltiSnips-trigger-functions|
3.2.2 Custom autocommands |UltiSnips-custom-autocommands|
3.2.3 Path to Python Module |UltiSnips-python-module-path|
3.3 Snippet Search Path |UltiSnips-snippet-search-path|
3.4 Warning About Select Mode Mappings |UltiSnips-warning-smappings|
3.5 Functions |UltiSnips-functions|
3.5.1 UltiSnips#AddSnippetWithPriority |UltiSnips#AddSnippetWithPriority|
3.5.2 UltiSnips#Anon |UltiSnips#Anon|
3.5.3 UltiSnips#SnippetsInCurrentScope |UltiSnips#SnippetsInCurrentScope|
3.6 Missing python support |UltiSnips-python-warning|
4. Syntax |UltiSnips-syntax|
4.1 Adding Snippets |UltiSnips-adding-snippets|
4.1.1 Character Escaping |UltiSnips-character-escaping|
4.2 Plaintext Snippets |UltiSnips-plaintext-snippets|
4.3 Visual Placeholder |UltiSnips-visual-placeholder|
4.4 Interpolation |UltiSnips-interpolation|
4.4.1 Shellcode |UltiSnips-shellcode|
4.4.2 VimScript |UltiSnips-vimscript|
4.4.3 Python |UltiSnips-python|
4.4.4 Global Snippets |UltiSnips-globals|
4.5 Tabstops and Placeholders |UltiSnips-tabstops|
4.6 Mirrors |UltiSnips-mirrors|
4.7 Transformations |UltiSnips-transformations|
4.7.1 Replacement String |UltiSnips-replacement-string|
4.7.2 Demos |UltiSnips-demos|
4.8 Clearing snippets |UltiSnips-clearing-snippets|
4.9 Context snippets |UltiSnips-context-snippets|
4.10 Snippet actions |UltiSnips-snippet-actions|
4.10.1 Pre-expand actions |UltiSnips-pre-expand-actions|
4.10.2 Post-expand actions |UltiSnips-post-expand-actions|
4.10.3 Post-jump actions |UltiSnips-post-jump-actions|
4.11 Autotrigger |UltiSnips-autotrigger|
5. UltiSnips and Other Plugins |UltiSnips-other-plugins|
5.1 Existing Integrations |UltiSnips-integrations|
5.2 Extending UltiSnips |UltiSnips-extending|
6. Helping Out |UltiSnips-helping|
7. Contributors |UltiSnips-contributors|
This plugin only works if 'compatible' is not set.
{Vi does not have any of these features}
{only available when |+python| or |+python3| have been enabled at compile time}
==============================================================================
1. Description *UltiSnips-description*
UltiSnips provides snippet management for the Vim editor. A snippet is a short
piece of text that is either re-used often or contains a lot of redundant
text. UltiSnips allows you to insert a snippet with only a few key strokes.
Snippets are common in structured text like source code but can also be used
for general editing like, for example, inserting a signature in an email or
inserting the current date in a text file.
@SirVer posted several short screencasts which make a great introduction to
UltiSnips, illustrating its features and usage.
http://www.sirver.net/blog/2011/12/30/first-episode-of-ultisnips-screencast/
http://www.sirver.net/blog/2012/01/08/second-episode-of-ultisnips-screencast/
http://www.sirver.net/blog/2012/02/05/third-episode-of-ultisnips-screencast/
http://www.sirver.net/blog/2012/03/31/fourth-episode-of-ultisnips-screencast/
Also the excellent [Vimcasts](http://vimcasts.org) dedicated three episodes to
UltiSnips:
http://vimcasts.org/episodes/meet-ultisnips/
http://vimcasts.org/episodes/ultisnips-python-interpolation/
http://vimcasts.org/episodes/ultisnips-visual-placeholder/
1.1 Requirements *UltiSnips-requirements*
----------------
This plugin works with Vim version 7.4 or later. It only works if the
'compatible' setting is not set.
This plugin is tested against Python 2.7, 3.3 or 3.4. All other versions are
unsupported, but might work.
The Python 2.x or Python 3.x interface must be available. In other words, Vim
must be compiled with either the |+python| feature or the |+python3| feature.
The following commands show how to test if you have python compiled in Vim.
They print '1' if the python version is compiled in, '0' if not.
Test if Vim is compiled with python version 2.x: >
:echo has("python")
The python version Vim is linked against can be found with: >
:py import sys; print(sys.version)
Test if Vim is compiled with python version 3.x: >
:echo has("python3")
The python version Vim is linked against can be found with: >
:py3 import sys; print(sys.version)
Note that Vim is maybe not using your system-wide installed python version, so
make sure to check the Python version inside of Vim.
UltiSnips attempts to auto-detect which python version is compiled into Vim.
Unfortunately, in some versions of Vim this detection does not work.
In that case you have to explicitly tell UltiSnips which version to use using
the 'UltiSnipsUsePythonVersion' global variable.
To use python version 2.x: >
let g:UltiSnipsUsePythonVersion = 2
To use python version 3.x: >
let g:UltiSnipsUsePythonVersion = 3
1.2 Acknowledgments *UltiSnips-acknowledgments*
-------------------
UltiSnips was inspired by the snippets feature of TextMate
(http://macromates.com/), the GUI text editor for Mac OS X. Managing snippets
in Vim is not new. I want to thank Michael Sanders, the author of snipMate,
for some implementation details I borrowed from his plugin and for the
permission to use his snippets.
=============================================================================
2. Installation and Updating *UltiSnips-installnupdate*
The recommended way of getting UltiSnips is to track SirVer/ultisnips on
github. The master branch is always stable.
Using Pathogen: *UltiSnips-using-pathogen*
If you are a pathogen user, you can track the official mirror of UltiSnips on
github: >
$ cd ~/.vim/bundle && git clone git://github.com/SirVer/ultisnips.git
If you also want the default snippets, also track >
$ cd ~/.vim/bundle && git clone git://github.com/honza/vim-snippets.git
See the pathogen documentation for more details on how to update a bundle.
Using a downloaded packet: *UltiSnips-using-a-downloaded-packet*
Download the packet and unpack into a directory of your choice. Then add this
directory to your Vim runtime path by adding this line to your vimrc file. >
set runtimepath+=~/.vim/ultisnips_rep
UltiSnips also needs that Vim sources files from the ftdetect/ directory.
Unfortunately, Vim only allows this directory in the .vim directory. You
therefore have to symlink/copy the files: >
mkdir -p ~/.vim/ftdetect/
ln -s ~/.vim/ultisnips_rep/ftdetect/* ~/.vim/ftdetect/
Restart Vim and UltiSnips should work. To access the help, use >
:helptags ~/.vim/ultisnips_rep/doc
:help UltiSnips
UltiSnips comes without snippets. The default snippets can be found here:
https://github.com/honza/vim-snippets
=============================================================================
3. Settings & Commands *UltiSnips-settings*
3.1 Commands *UltiSnips-commands*
------------
*:UltiSnipsEdit*
The UltiSnipsEdit command opens a private snippet definition file for the
current filetype. If no snippet file exists, a new file is created. If used as
UltiSnipsEdit! all public snippet files are taken into account too. If
multiple files match the search, the user gets to choose the file.
There are several variables associated with the UltiSnipsEdit command.
*g:UltiSnipsEditSplit*
g:UltiSnipsEditSplit Defines how the edit window is opened. Possible
values:
|normal| Default. Opens in the current window.
|horizontal| Splits the window horizontally.
|vertical| Splits the window vertically.
|context| Splits the window vertically or
horizontally depending on context.
*g:UltiSnipsSnippetsDir*
g:UltiSnipsSnippetsDir
Defines the directory private snippet definition
files are stored in. For example, if the variable
is set to "~/.vim/mydir/UltiSnips" and the current
'filetype' is "cpp", then :UltiSnipsEdit will open
"~/.vim/mydir/UltiSnips/cpp.snippets" if file is
not empty, if it's empty :UltiSnipsEdit will see
for non-empty files in directories
g:UltiSnipsSnippetDirectories, if nothing found,
:UltiSnipsEdit will open new file in
g:UltiSnipsSnippetsDir.
Note that directories named "snippets" are
reserved for snipMate snippets and cannot be used.
*g:UltiSnipsSnippetDirectories*
g:UltiSnipsSnippetDirectories
Defines the directories for looking for snippets.
Do not mix up this variable with previous one.
More information about that variable can
be found at section |UltiSnips-snippet-search-path|.
*g:UltiSnipsEnableSnipMate*
g:UltiSnipsEnableSnipMate
Enable looking for SnipMate snippets in
&runtimepath. UltiSnips will search only for
directories named 'snippets' while looking for
SnipMate snippets. Defaults to "1", so UltiSnips
will look for SnipMate snippets.
*:UltiSnipsAddFiletypes*
The UltiSnipsAddFiletypes command allows for explicit merging of other snippet
filetypes for the current buffer. For example, if you edit a .rst file but
also want the Lua snippets to be available you can issue the command >
:UltiSnipsAddFiletypes rst.lua
using the dotted filetype syntax. Order is important, the first filetype in
this list will be the one used for UltiSnipsEdit and the list is
ordered by evaluation priority. Consequently, you might add this to your
ftplugin/rails.vim >
:UltiSnipsAddFiletypes rails.ruby
I mention rails first because I want to edit rails snippets when using
UltiSnipsEdit and because rails snippets should overwrite equivalent ruby
snippets. The priority will now be rails -> ruby -> all. If you have some
special programming snippets that should have lower priority than your ruby
snippets you can call >
:UltiSnipsAddFiletypes ruby.programming
The priority will then be rails -> ruby -> programming -> all.
3.2 Triggers *UltiSnips-triggers*
------------
*g:UltiSnipsExpandTrigger* *g:UltiSnipsListSnippets*
*g:UltiSnipsJumpForwardTrigger* *g:UltiSnipsJumpBackwardTrigger*
You can define the keys used to trigger UltiSnips actions by setting global
variables. Variables define the keys used to expand a snippet, jump forward
and jump backwards within a snippet, and list all available snippets in the
current expand context. Be advised, that some terminal emulators don't send
<c-tab> to the running program. The variables with their default values are: >
g:UltiSnipsExpandTrigger <tab>
g:UltiSnipsListSnippets <c-tab>
g:UltiSnipsJumpForwardTrigger <c-j>
g:UltiSnipsJumpBackwardTrigger <c-k>
UltiSnips will only map the jump triggers while a snippet is active to
interfere as little as possible with other mappings.
The default value for g:UltiSnipsJumpBackwardTrigger interferes with the
built-in complete function: |i_CTRL-X_CTRL-K|. A workaround is to add the
following to your vimrc file or switching to a plugin like Supertab or
YouCompleteMe. >
inoremap <c-x><c-k> <c-x><c-k>
3.2.1 Using your own trigger functions *UltiSnips-trigger-functions*
--------------------------------------
For advanced users there are four functions that you can map directly to a
key and that correspond to some of the triggers previously defined:
g:UltiSnipsExpandTrigger <--> UltiSnips#ExpandSnippet
g:UltiSnipsJumpForwardTrigger <--> UltiSnips#JumpForwards
g:UltiSnipsJumpBackwardTrigger <--> UltiSnips#JumpBackwards
If you have g:UltiSnipsExpandTrigger and g:UltiSnipsJumpForwardTrigger set
to the same value then the function you are actually going to use is
UltiSnips#ExpandSnippetOrJump.
Each time any of the functions UltiSnips#ExpandSnippet,
UltiSnips#ExpandSnippetOrJump, UltiSnips#JumpForwards or
UltiSnips#JumpBackwards is called a global variable is set that contains the
return value of the corresponding function.
The corresponding variables and functions are:
UltiSnips#ExpandSnippet --> g:ulti_expand_res (0: fail, 1: success)
UltiSnips#ExpandSnippetOrJump --> g:ulti_expand_or_jump_res (0: fail,
1: expand, 2: jump)
UltiSnips#JumpForwards --> g:ulti_jump_forwards_res (0: fail, 1: success)
UltiSnips#JumpBackwards --> g:ulti_jump_backwards_res (0: fail, 1: success)
To see how these return values may come in handy, suppose that you want to map
a key to expand or jump, but if none of these actions is successful you want
to call another function. UltiSnips already does this automatically for
supertab, but this allows you individual fine tuning of your Tab key usage.
Usage is as follows: You define a function >
let g:ulti_expand_or_jump_res = 0 "default value, just set once
function! Ulti_ExpandOrJump_and_getRes()
call UltiSnips#ExpandSnippetOrJump()
return g:ulti_expand_or_jump_res
endfunction
then you define your mapping as >
inoremap <NL> <C-R>=(Ulti_ExpandOrJump_and_getRes() > 0)?"":IMAP_Jumpfunc('', 0)<CR>
and if the you can't expand or jump from the current location then the
alternative function IMAP_Jumpfunc('', 0) is called.
3.2.2 Custom autocommands *UltiSnips-custom-autocommands*
-------------------------
Note Autocommands must *not* change the buffer in any way. If lines are added,
deleted, or modified it will confuse UltiSnips which might scramble your
snippets contents.
*UltiSnipsEnterFirstSnippet* *UltiSnipsExitLastSnippet*
For maximum compatibility with other plug-ins, UltiSnips sets up some special
state, include mappings and autocommands, when a snippet starts being
expanded, and tears them down once the last snippet has been exited. In order
to make it possible to override these "inner" settings, it fires the following
"User" autocommands:
UltiSnipsEnterFirstSnippet
UltiSnipsExitLastSnippet
For example, to call a pair of custom functions in response to these events,
you might do: >
autocmd! User UltiSnipsEnterFirstSnippet
autocmd User UltiSnipsEnterFirstSnippet call CustomInnerKeyMapper()
autocmd! User UltiSnipsExitLastSnippet
autocmd User UltiSnipsExitLastSnippet call CustomInnerKeyUnmapper()
Note that snippet expansion may be nested, in which case
|UltiSnipsEnterFirstSnippet| will fire only as the first (outermost) snippet
is entered, and |UltiSnipsExitLastSnippet| will only fire once the last
(outermost) snippet have been exited.
3.2.3 Path to Python module *UltiSnips-python-module-path*
---------------------------
For even more advanced usage, you can directly write python functions using
UltiSnip's python modules.
Here is a small example funtion that expands a snippet: >
function! s:Ulti_ExpandSnip()
Python << EOF
import sys, vim
from UltiSnips import UltiSnips_Manager
UltiSnips_Manager.expand()
EOF
return ""
endfunction
3.3 Snippet Search Path *UltiSnips-snippet-search-path*
-----------------------
UltiSnips snippet definition files are stored in one or more directories.
There are several variables used to indicate those directories and to define
how UltiSnips loads snippets.
Snippet definition files are stored in snippet directories. A snippet
directory must be a subdirectory of a directory defined in the 'runtimepath'
option. The variable g:UltiSnipsSnippetDirectories defines a list of names
used for snippet directories. Note that "snippets" is reserved for snipMate
snippets and cannot be used. The default is shown below. >
let g:UltiSnipsSnippetDirectories=["UltiSnips"]
UltiSnips will search each 'runtimepath' directory for the subdirectory names
defined in g:UltiSnipsSnippetDirectories in the order they are defined. For
example, if you keep your snippets in a .vim subdirectory called
"mycoolsnippets" and you want to make use of the default snippets that come
with UltiSnips, add the following to your vimrc file. >
let g:UltiSnipsSnippetDirectories=["UltiSnips", "mycoolsnippets"]
If you do not want to use the third party snippets that come with plugins,
define the variable accordingly: >
let g:UltiSnipsSnippetDirectories=["mycoolsnippets"]
You can also redefine the search path on a buffer by buffer basis by setting
the variable b:UltiSnipsSnippetDirectories. This variable takes precedence
over the global variable.
|UltiSnips-adding-snippets| explains which files are parsed for a given filetype.
If only one directory is specified in this variable and this directory is
specified by absolute path, UltiSnips will not look for snippets in
&runtimepath, which can lead to significant speedup. So, the common case is:
let g:UltiSnipsSnippetDirectories=[$HOME.'/.vim/UltiSnips']
However, you will not able to use snippets that are shipped with third party
plugins out of the box. You'll need to copy them into your chosen directory.
3.4 Warning About Select Mode Mappings *UltiSnips-warning-smappings*
--------------------------------------
Vim's help document for |mapmode-s| states: >
NOTE: Mapping a printable character in Select mode may confuse the user.
It's better to explicitly use :xmap and :smap for printable characters. Or
use :sunmap after defining the mapping.
However, most Vim plugins, including some default Vim plugins, do not adhere
to this. UltiSnips uses Select mode to mark tabstops in snippets for
overwriting. Existing Visual+Select mode mappings will interfere. Therefore,
UltiSnips issues a |:sunmap| command to remove each Select mode mapping for
printable characters. No other mappings are touched. In particular, UltiSnips
does not change existing normal, insert or visual mode mappings.
If this behavior is not desired, you can disable it by adding this line to
your vimrc file. >
let g:UltiSnipsRemoveSelectModeMappings = 0
If you want to disable this feature for specific mappings only, add them to
the list of mappings to be ignored. For example, the following lines in your
vimrc file will unmap all Select mode mappings except those mappings
containing either the string "somePlugin" or the string "otherPlugin" in its
complete definition as listed by the |:smap| command. >
let g:UltiSnipsRemoveSelectModeMappings = 1
let g:UltiSnipsMappingsToIgnore = [ "somePlugin", "otherPlugin" ]
3.5 Functions *UltiSnips-functions*
-------------
UltiSnips provides some functions for extending core functionality.
3.5.1 UltiSnips#AddSnippetWithPriority *UltiSnips#AddSnippetWithPriority*
The first function is UltiSnips#AddSnippetWithPriority(trigger, value, description,
options, filetyp, priority). It adds a new snippet with the provided trigger, value,
description, and options to the current list of snippets. See
|UltiSnips-syntax| for details on the meaning of the function arguments. The
Priority is a number that defines which snippet should be preferred over
others. See the priority keyword in|UltiSnips-add-snippets|.
3.5.2 UltiSnips#Anon *UltiSnips#Anon*
The second function is UltiSnips#Anon(value, ...). It expands an anonymous
snippet. Anonymous snippets are defined on the spot, expanded and immediately
discarded again. Anonymous snippets are not added to the global list of
snippets, so they cannot be expanded a second time unless the function is
called again. The function takes three optional arguments, in order: trigger,
description, options. Arguments coincide with the arguments of the
|UltiSnips#AddSnippetWithPriority| function of the same name. The trigger and
options arguments can change the way the snippet expands. Same options
can be specified as in the snippet definition. See full list of options at
|UltiSnips-snippet-options|. The description is unused at this point.
An example use case might be this line from a reStructuredText plugin file:
inoremap <silent> $$ $$<C-R>=UltiSnips#Anon(':latex:\`$1\`', '$$')<cr>
This expands the snippet whenever two $ signs are typed.
Note: The right-hand side of the mapping starts with an immediate retype of
the '$$' trigger and passes '$$' to the function as the trigger argument.
This is required in order for UltiSnips to have access to the characters
typed so it can determine if the trigger matches or not.
3.5.3 UltiSnips#SnippetsInCurrentScope *UltiSnips#SnippetsInCurrentScope*
A third function is UltiSnips#SnippetsInCurrentScope which is the equivalent
of snipmate GetSnipsInCurrentScope function.
This function simply returns a vim dictionary with the snippets whose trigger
matches the current word. If you need all snippets information of current
buffer, you can simply pass 1 (which means all) as first argument of this
function, and use a global variable g:current_ulti_dict_info to get the
result (see example below).
This function does not add any new functionality to ultisnips directly but
allows to use third party plugins to integrate the current available snippets.
An example of such third party plugin is SnippetCompleteSnipMate which uses
the function GetSnipsInCurrentScope to integrate the current available
snippets with user defined abbreviations and provides these and a completion
menu.
This script is located in
http://www.vim.org/scripts/script.php?script_id=4276.
Note: If you check the above website it lists two dependencies: the
SnippetComplete plugin and snipmate.
You do need the SnippetComplete plugin but you obviously don't need snipmate,
you just have to define the function GetSnipsInCurrentScope. Put the following
in your vimrc:
function! GetSnipsInCurrentScope()
return UltiSnips#SnippetsInCurrentScope()
endfunction
As a second example on how to use this function consider the following
function and mapping definition:
function! ExpandPossibleShorterSnippet()
if len(UltiSnips#SnippetsInCurrentScope()) == 1 "only one candidate...
let curr_key = keys(UltiSnips#SnippetsInCurrentScope())[0]
normal diw
exe "normal a" . curr_key
exe "normal a "
return 1
endif
return 0
endfunction
inoremap <silent> <C-L> <C-R>=(ExpandPossibleShorterSnippet() == 0? '': UltiSnips#ExpandSnippet())<CR>
If the trigger for your snippet is lorem, you type lor, and you have no other
snippets whose trigger matches lor then hitting <C-L> will expand to whatever
lorem expands to.
A third example on how to use this function to extract all snippets of
current buffer: >
function! GetAllSnippets()
call UltiSnips#SnippetsInCurrentScope(1)
let list = []
for [key, info] in items(g:current_ulti_dict_info)
let parts = split(info.location, ':')
call add(list, {
\"key": key,
\"path": parts[0],
\"linenr": parts[1],
\"description": info.description,
\})
endfor
return list
endfunction
The new variable g:current_ulti_dict_info is made to avoid confilct with
exists third party plugins. The definition location contains file path and
line number is also included in this variable.
3.6 Warning about missing python support *UltiSnips-python-warning*
----------------------------------------
When UltiSnips is loaded, it will check that the running Vim was compiled with
python support. If no support is detected, a warning will be displayed and
loading of UltiSnips will be skipped.
If you would like to suppress this warning message, you may add the following
line to your vimrc file.
let g:UltiSnipsNoPythonWarning = 1
This may be useful if your Vim configuration files are shared across several
systems where some of them may not have Vim compiled with python support.
=============================================================================
4. Syntax *UltiSnips-syntax*
This chapter describes how to write your own snippets and snippet definition
syntax. Examples are used to help illustrate.
4.1 Adding Snippets *UltiSnips-adding-snippets*
-------------------
See |UltiSnips-snippet-search-path| for an explanation of where directories
with snippet definitions should be located.
Using a strategy similar to how Vim detects |ftplugins|, UltiSnips iterates
over the snippet definition directories looking for files with names of the
following patterns: ft.snippets, ft_*.snippets, or ft/*, where "ft" is the
'filetype' of the current document and "*" is a shell-like wildcard matching
any string including the empty string. The following table shows some typical
snippet filenames and their associated filetype.
snippet filename filetype ~
ruby.snippets ruby
perl.snippets perl
c.snippets c
c_my.snippets c
c/a c
c/b.snippets c
all.snippets *all
all/a.snippets *all
* The 'all' filetype is unique. It represents snippets available for use when
editing any document regardless of the filetype. A date insertion snippet, for
example, would fit well in the all.snippets file.
UltiSnips understands Vim's dotted filetype syntax. For example, if you define
a dotted filetype for the CUDA C++ framework, e.g. ":set ft=cuda.cpp", then
UltiSnips will search for and activate snippets for both the cuda and cpp
filetypes.
The snippets file syntax is simple. All lines starting with a # character are
considered comments. Comments are ignored by UltiSnips. Use them to document
snippets.
A line beginning with the keyword 'extends' provides a way of combining
snippet files. When the 'extends' directive is included in a snippet file, it
instructs UltiSnips to include all snippets from the indicated filetypes.
The syntax looks like this: >
extends ft1, ft2, ft3
For example, the first line in cpp.snippets looks like this: >
extends c
When UltiSnips activates snippets for a cpp file, it first looks for all c
snippets and activates them as well. This is a convenient way to create
specialized snippet files from more general ones. Multiple 'extends' lines are
permitted in a snippet file, and they can be included anywhere in the file.
A line beginning with the keyword 'priority' sets the priority for all
snippets defined in the current file after this line. The default priority for
a file is always 0. When a snippet should be expanded, UltiSnips will collect
all snippet definitions from all sources that match the trigger and keep only
the ones with the highest priority. For example, all shipped snippets have a
priority < 0, so that user defined snippets always overwrite shipped snippets.
A line beginning with the keyword 'snippet' marks the beginning of snippet
definition and a line starting with the keyword 'endsnippet' marks the end.
The snippet definition is placed between the lines. Here is a snippet of an
'if' statement for the Unix shell (sh) filetype.
snippet if "if ... then (if)"
if ${2:[[ ${1:condition} ]]}; then
${0:#statements}
fi
endsnippet
The start line takes the following form: >
snippet tab_trigger [ "description" [ options ] ]
The tab_trigger is required, but the description and options are optional.
The 'tab_trigger' is the word or string sequence used to trigger the snippet.
Generally a single word is used but the tab_trigger can include spaces. If you
wish to include spaces, you must wrap the tab trigger in quotes. >
snippet "tab trigger" [ "description" [ options ] ]
The quotes are not part of the trigger. To activate the snippet type: tab trigger
followed by the snippet expand character.
It is not technically necessary to use quotes to wrap a trigger with spaces.
Any matching characters will do. For example, this is a valid snippet starting
line. >
snippet !tab trigger! [ "description" [ options ] ]
Quotes can be included as part of the trigger by wrapping the trigger in
another character. >
snippet !"tab trigger"! [ "description" [ options ] ]
To activate this snippet one would type: "tab trigger"
The 'description' is a string describing the trigger. It is helpful for
documenting the snippet and for distinguishing it from other snippets with the
same tab trigger. When a snippet is activated and more than one tab trigger
match, UltiSnips displays a list of the matching snippets with their
descriptions. The user then selects the snippet they want.
*UltiSnips-snippet-options*
The 'options' control the behavior of the snippet. Options are indicated by
single characters. The 'options' characters for a snippet are combined into
a word without spaces.
The options currently supported are: >
b Beginning of line - A snippet with this option is expanded only if the
tab trigger is the first word on the line. In other words, if only
whitespace precedes the tab trigger, expand. The default is to expand
snippets at any position regardless of the preceding non-whitespace
characters.
i In-word expansion - By default a snippet is expanded only if the tab
trigger is the first word on the line or is preceded by one or more
whitespace characters. A snippet with this option is expanded
regardless of the preceding character. In other words, the snippet can
be triggered in the middle of a word.
w Word boundary - With this option, the snippet is expanded if
the tab trigger start matches a word boundary and the tab trigger end
matches a word boundary. In other words the tab trigger must be
preceded and followed by non-word characters. Word characters are
defined by the 'iskeyword' setting. Use this option, for example, to
permit expansion where the tab trigger follows punctuation without
expanding suffixes of larger words.
r Regular expression - With this option, the tab trigger is expected to
be a python regular expression. The snippet is expanded if the recently
typed characters match the regular expression. Note: The regular
expression MUST be quoted (or surrounded with another character) like a
multi-word tab trigger (see above) whether it has spaces or not. A
resulting match is passed to any python code blocks in the snippet
definition as the local variable "match".
t Do not expand tabs - If a snippet definition includes leading tab
characters, by default UltiSnips expands the tab characters honoring
the Vim 'shiftwidth', 'softtabstop', 'expandtab' and 'tabstop'
indentation settings. (For example, if 'expandtab' is set, the tab is
replaced with spaces.) If this option is set, UltiSnips will ignore the
Vim settings and insert the tab characters as is. This option is useful
for snippets involved with tab delimited formats, for example.
s Remove whitespace immediately before the cursor at the end of a line
before jumping to the next tabstop. This is useful if there is a
tabstop with optional text at the end of a line.
m Trim all whitespaces from right side of snippet lines. Useful when
snippet contains empty lines which should remain empty after expanding.
Without this option empty lines in snippets definition will have
indentation too.
e Context snippets - With this option expansion of snippet can be
controlled not only by previous characters in line, but by any given
python expression. This option can be specified along with other
options, like 'b'. See |UltiSnips-context-snippets| for more info.
A Snippet will be triggered automatically, when condition matches.
See |UltiSnips-autotrigger| for more info.
The end line is the 'endsnippet' keyword on a line by itself. >
endsnippet
When parsing snippet files, UltiSnips chops the trailing newline character
from the 'endsnippet' end line.
4.1.1 Character Escaping: *UltiSnips-character-escaping*
In snippet definitions, the characters '`', '{', '$' and '\' have special
meaning. If you want to insert one of these characters literally, escape them
with a backslash, '\'.
4.2 Plaintext Snippets *UltiSnips-plaintext-snippets*
----------------------
To illustrate plaintext snippets, let's begin with a simple example. You can
try the examples yourself. Simply edit a new file with Vim. Example snippets
will be added to the 'all.snippets' file, so you'll want to open it in Vim for
editing as well. >
~/.vim/UltiSnips/all.snippets
Add this snippet to 'all.snippets' and save the file.
------------------- SNIP -------------------
snippet bye "My mail signature"
Good bye, Sir. Hope to talk to you soon.
- Arthur, King of Britain
endsnippet
------------------- SNAP -------------------
UltiSnips detects when you write changes to a snippets file and automatically
makes the changes active. So in the empty buffer, type the tab trigger 'bye'
and then press the <Tab> key.
bye<Tab> -->
Good bye, Sir. Hope to talk to you soon.
- Arthur, King of Britain
The word 'bye' will be replaced with the text of the snippet definition.
4.3 Visual Placeholder *UltiSnips-visual-placeholder*
----------------------
Snippets can contain a special placeholder called ${VISUAL}. The ${VISUAL}
variable is expanded with the text selected just prior to expanding the
snippet.
To see how a snippet with a ${VISUAL} placeholder works, define a snippet with
the placeholder, use Vim's Visual mode to select some text, and then press the
key you use to trigger expanding a snippet (see g:UltiSnipsExpandTrigger). The
selected text is deleted, and you are dropped into Insert mode. Now type the
snippet tab trigger and press the key to trigger expansion. As the snippet
expands, the previously selected text is printed in place of the ${VISUAL}
placeholder.
The ${VISUAL} placeholder can contain default text to use when the snippet has
been triggered when not in Visual mode. The syntax is: >
${VISUAL:default text}
The ${VISUAL} placeholder can also define a transformation (see
|UltiSnips-transformations|). The syntax is: >
${VISUAL:default/search/replace/option}.
Here is a simple example illustrating a visual transformation. The snippet
will take selected text, replace every instance of "should" within it with
"is" , and wrap the result in tags.
------------------- SNIP -------------------
snippet t
<tag>${VISUAL:inside text/should/is/g}</tag>
endsnippet
------------------- SNAP -------------------
Start with this line of text: >
this should be cool
Position the cursor on the word "should", then press the key sequence: viw
(visual mode -> select inner word). Then press <Tab>, type "t" and press <Tab>
again. The result is: >
-> this <tag>is</tag> be cool
If you expand this snippet while not in Visual mode (e.g., in Insert mode type
t<Tab>), you will get: >
<tag>inside text</tag>
4.4 Interpolation *UltiSnips-interpolation*
-----------------
4.4.1 Shellcode: *UltiSnips-shellcode*
Snippets can include shellcode. Put a shell command in a snippet and when the
snippet is expanded, the shell command is replaced by the output produced when
the command is executed. The syntax for shellcode is simple: wrap the code in
backticks, '`'. When a snippet is expanded, UltiSnips runs shellcode by first
writing it to a temporary script and then executing the script. The shellcode
is replaced by the standard output. Anything you can run as a script can be
used in shellcode. Include a shebang line, for example, #!/usr/bin/perl, and
your snippet has the ability to run scripts using other programs, perl, for
example.
Here are some examples. This snippet uses a shell command to insert the
current date.
------------------- SNIP -------------------
snippet today
Today is the `date +%d.%m.%y`.
endsnippet
------------------- SNAP -------------------
today<tab> ->
Today is the 15.07.09.
This example inserts the current date using perl.
------------------- SNIP -------------------
snippet today
Today is `#!/usr/bin/perl
@a = localtime(); print $a[3] . '.' . $a[4] . '.' . ($a[5]+1900);`.
endsnippet
------------------- SNAP -------------------
today<tab> ->
Today is 15.6.2009.
4.4.2 VimScript: *UltiSnips-vimscript*
You can also use Vim scripts (sometimes called VimL) in interpolation. The
syntax is similar to shellcode. Wrap the code in backticks and to distinguish
it as a Vim script, start the code with '!v'. Here is an example that counts
the indent of the current line:
------------------- SNIP -------------------
snippet indent
Indent is: `!v indent(".")`.
endsnippet
------------------- SNAP -------------------
(note the 4 spaces in front): indent<tab> ->
(note the 4 spaces in front): Indent is: 4.
4.4.3 Python: *UltiSnips-python*
Python interpolation is by far the most powerful. The syntax is similar to Vim
scripts except code is started with '!p'. Python scripts can be run using the
python shebang '#!/usr/bin/python', but using the '!p' format comes with some
predefined objects and variables, which can simplify and shorten code. For
example, a 'snip' object instance is implied in python code. Python code using
the '!p' indicator differs in another way. Generally when a snippet is
expanded the standard output of code replaces the code. With python code the
value of the 'rv' property of the 'snip' instance replaces the code. Standard
output is ignored.
The variables automatically defined in python code are: >
fn - The current filename
path - The complete path to the current file
t - The values of the placeholders, t[1] is the text of ${1}, etc.
snip - UltiSnips.TextObjects.SnippetUtil object instance. Has methods
that simplify indentation handling.
context - Result of context condition. See |UltiSnips-context-snippets|.
The 'snip' object provides the following methods: >
snip.mkline(line="", indent=None):
Returns a line ready to be appended to the result. If indent
is None, then mkline prepends spaces and/or tabs appropriate to the
current 'tabstop' and 'expandtab' variables.
snip.shift(amount=1):
Shifts the default indentation level used by mkline right by the
number of spaces defined by 'shiftwidth', 'amount' times.
snip.unshift(amount=1):
Shifts the default indentation level used by mkline left by the
number of spaces defined by 'shiftwidth', 'amount' times.
snip.reset_indent():
Resets the indentation level to its initial value.
snip.opt(var, default):
Checks if the Vim variable 'var' has been set. If so, it returns the
variable's value; otherwise, it returns the value of 'default'.
The 'snip' object provides some properties as well: >
snip.rv:
'rv' is the return value, the text that will replace the python block
in the snippet definition. It is initialized to the empty string. This
deprecates the 'res' variable.
snip.c:
The text currently in the python block's position within the snippet.
It is set to empty string as soon as interpolation is completed. Thus
you can check if snip.c is != "" to make sure that the interpolation
is only done once. This deprecates the "cur" variable.
snip.v:
Data related to the ${VISUAL} placeholder. The property has two
attributes:
snip.v.mode ('v', 'V', '^V', see |visual-mode| )
snip.v.text The text that was selected.
snip.fn:
The current filename.
snip.basename:
The current filename with the extension removed.
snip.ft:
The current filetype.
snip.p:
Last selected placeholder. Will contain placeholder object with
following properties:
'current_text' - text in the placeholder on the moment of selection;
'start' - placeholder start on the moment of selection;
'end' - placeholder end on the moment of selection;
For your convenience, the 'snip' object also provides the following
operators: >
snip >> amount:
Equivalent to snip.shift(amount)
snip << amount:
Equivalent to snip.unshift(amount)
snip += line:
Equivalent to "snip.rv += '\n' + snip.mkline(line)"
Any variables defined in a python block can be used in other python blocks
that follow within the same snippet. Also, the python modules 'vim', 're',
'os', 'string' and 'random' are pre-imported within the scope of snippet code.
Other modules can be imported using the python 'import' command.
Python code allows for very flexible snippets. For example, the following
snippet mirrors the first tabstop value on the same line but right aligned and
in uppercase.
------------------- SNIP -------------------
snippet wow
${1:Text}`!p snip.rv = (75-2*len(t[1]))*' '+t[1].upper()`
endsnippet
------------------- SNAP -------------------
wow<tab>Hello World ->
Hello World HELLO WORLD
The following snippet uses the regular expression option and illustrates
regular expression grouping using python's match object. It shows that the
expansion of a snippet can depend on the tab trigger used to define the
snippet, and that tab trigger itself can vary.
------------------- SNIP -------------------
snippet "be(gin)?( (\S+))?" "begin{} / end{}" br
\begin{${1:`!p
snip.rv = match.group(3) if match.group(2) is not None else "something"`}}
${2:${VISUAL}}
\end{$1}$0
endsnippet
------------------- SNAP -------------------
be<tab>center<c-j> ->
\begin{center}
\end{center}
------------------- SNAP -------------------
be center<tab> ->