vim/UltiSnips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

refactor documentation with snippets loading procedure section (#954)

Browse Source 
I have:
* Created a new section "4.1.3 How snippets are loaded"
* Moved documentation from "4.1 Adding Snippets" section into "4.1.3 How snippets are loaded"
This commit is contained in:
Gordon 2018-04-18 06:34:07 +01:00 committed by UltiBot
parent 905e524924
commit 30e651fb1f
1 changed files with 201 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

409
doc/UltiSnips.txt
View File

@ -1,4 +1,4 @@
*UltiSnips.txt* For Vim version 7.0 or later. *UltiSnips.txt* For Vim version 7.4 or later.
The Ultimate Plugin for Snippets in Vim~ The Ultimate Plugin for Snippets in Vim~
@ -7,24 +7,28 @@ UltiSnips *snippet* *snippets* *UltiSnips*
1. Description |UltiSnips-description| 1. Description |UltiSnips-description|
1.1 Requirements |UltiSnips-requirements| 1.1 Requirements |UltiSnips-requirements|
1.2 Acknowledgments |UltiSnips-acknowledgments| 1.2 Acknowledgments |UltiSnips-acknowledgments|
2. Installation and Updating |UltiSnips-installnupdate| 2. Installation and Updating |UltiSnips-install-and-update|
3. Settings & Commands |UltiSnips-settings| 3. Settings & Commands |UltiSnips-settings|
3.1 Commands |UltiSnips-commands| 3.1 Commands |UltiSnips-commands|
3.1.1 UltiSnipsEdit |UltiSnipsEdit|
3.1.2 UltiSnipsAddFiletypes |UltiSnipsAddFiletypes|
3.2 Triggers |UltiSnips-triggers| 3.2 Triggers |UltiSnips-triggers|
3.2.1 Using your own trigger functions |UltiSnips-trigger-functions| 3.2.1 Trigger key mappings |UltiSnips-trigger-key-mappings|
3.2.2 Custom autocommands |UltiSnips-custom-autocommands| 3.2.2 Using your own trigger functions |UltiSnips-trigger-functions|
3.2.3 Path to Python Module |UltiSnips-python-module-path| 3.2.3 Custom autocommands |UltiSnips-custom-autocommands|
3.3 Snippet Search Path |UltiSnips-snippet-search-path| 3.2.4 Direct use of Python API |UltiSnips-use-python-api|
3.4 Warning About Select Mode Mappings |UltiSnips-warning-smappings| 3.3 Warning About Select Mode Mappings |UltiSnips-warning-smappings|
3.5 Functions |UltiSnips-functions| 3.4 Functions |UltiSnips-functions|
3.5.1 UltiSnips#AddSnippetWithPriority |UltiSnips#AddSnippetWithPriority| 3.4.1 UltiSnips#AddSnippetWithPriority |UltiSnips#AddSnippetWithPriority|
3.5.2 UltiSnips#Anon |UltiSnips#Anon| 3.4.2 UltiSnips#Anon |UltiSnips#Anon|
3.5.3 UltiSnips#SnippetsInCurrentScope |UltiSnips#SnippetsInCurrentScope| 3.4.3 UltiSnips#SnippetsInCurrentScope |UltiSnips#SnippetsInCurrentScope|
3.6 Missing python support |UltiSnips-python-warning| 3.5 Missing python support |UltiSnips-python-warning|
4. Syntax |UltiSnips-syntax| 4. Authoring snippets |UltiSnips-authoring-snippets|
4.1 Adding Snippets |UltiSnips-adding-snippets| 4.1 Basics |UltiSnips-basics|
4.1.1 Snippet Options |UltiSnips-snippet-options| 4.1.1 How snippets are loaded |UltiSnips-how-snippets-are-loaded|
4.1.2 Character Escaping |UltiSnips-character-escaping| 4.1.2 Basic syntax |UltiSnips-basic-syntax|
4.1.3 Snippet Options |UltiSnips-snippet-options|
4.1.4 Character Escaping |UltiSnips-character-escaping|
4.2 Plaintext Snippets |UltiSnips-plaintext-snippets| 4.2 Plaintext Snippets |UltiSnips-plaintext-snippets|
4.3 Visual Placeholder |UltiSnips-visual-placeholder| 4.3 Visual Placeholder |UltiSnips-visual-placeholder|
4.4 Interpolation |UltiSnips-interpolation| 4.4 Interpolation |UltiSnips-interpolation|
@ -38,7 +42,7 @@ UltiSnips *snippet* *snippets* *UltiSnips*
4.7.1 Replacement String |UltiSnips-replacement-string| 4.7.1 Replacement String |UltiSnips-replacement-string|
4.7.2 Demos |UltiSnips-demos| 4.7.2 Demos |UltiSnips-demos|
4.8 Clearing snippets |UltiSnips-clearing-snippets| 4.8 Clearing snippets |UltiSnips-clearing-snippets|
4.9 Context snippets |UltiSnips-context-snippets| 4.9 Custom context snippets |UltiSnips-custom-context-snippets|
4.10 Snippet actions |UltiSnips-snippet-actions| 4.10 Snippet actions |UltiSnips-snippet-actions|
4.10.1 Pre-expand actions |UltiSnips-pre-expand-actions| 4.10.1 Pre-expand actions |UltiSnips-pre-expand-actions|
4.10.2 Post-expand actions |UltiSnips-post-expand-actions| 4.10.2 Post-expand actions |UltiSnips-post-expand-actions|
@ -63,8 +67,8 @@ 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 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. 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 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 for general editing like inserting a signature in an email or inserting the
inserting the current date in a text file. current date in a text file.
@SirVer posted several short screencasts which make a great introduction to @SirVer posted several short screencasts which make a great introduction to
UltiSnips, illustrating its features and usage. UltiSnips, illustrating its features and usage.
@ -87,8 +91,8 @@ http://vimcasts.org/episodes/ultisnips-visual-placeholder/
This plugin works with Vim version 7.4 or later. It only works if the This plugin works with Vim version 7.4 or later. It only works if the
'compatible' setting is not set. 'compatible' setting is not set.
This plugin is tested against Python 2.7, 3.3 or 3.4. All other versions are This plugin is tested against Python 2.7 and 3.6 in Vim 7.4 and 8. All other
unsupported, but might work. combinations are unsupported, but might work.
The Python 2.x or Python 3.x interface must be available. In other words, Vim 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. must be compiled with either the |+python| feature or the |+python3| feature.
@ -131,7 +135,7 @@ permission to use his snippets.
============================================================================= =============================================================================
2. Installation and Updating *UltiSnips-installnupdate* 2. Installation and Updating *UltiSnips-install-and-update*
The recommended way of getting UltiSnips is to track SirVer/ultisnips on The recommended way of getting UltiSnips is to track SirVer/ultisnips on
github. The master branch is always stable. github. The master branch is always stable.
@ -156,9 +160,9 @@ 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. > directory to your Vim runtime path by adding this line to your vimrc file. >
set runtimepath+=~/.vim/ultisnips_rep set runtimepath+=~/.vim/ultisnips_rep
UltiSnips also needs that Vim sources files from the ftdetect/ directory. UltiSnips also needs Vim files from the ftdetect/ directory. Unfortunately,
Unfortunately, Vim only allows this directory in the .vim directory. You Vim only allows this directory in the .vim directory. You therefore have to
therefore have to symlink/copy the files: > symlink/copy the files: >
mkdir -p ~/.vim/ftdetect/ mkdir -p ~/.vim/ftdetect/
ln -s ~/.vim/ultisnips_rep/ftdetect/* ~/.vim/ftdetect/ ln -s ~/.vim/ultisnips_rep/ftdetect/* ~/.vim/ftdetect/
@ -166,15 +170,17 @@ Restart Vim and UltiSnips should work. To access the help, use >
:helptags ~/.vim/ultisnips_rep/doc :helptags ~/.vim/ultisnips_rep/doc
:help UltiSnips :help UltiSnips
UltiSnips comes without snippets. The default snippets can be found here: UltiSnips comes without snippets. An excellent selection of snippets can be
https://github.com/honza/vim-snippets found here: https://github.com/honza/vim-snippets
============================================================================= =============================================================================
3. Settings & Commands *UltiSnips-settings* 3. Settings & Commands *UltiSnips-settings*
3.1 Commands *UltiSnips-commands* 3.1 Commands *UltiSnips-commands*
------------ ------------
*:UltiSnipsEdit*
3.1.1 UltiSnipsEdit *:UltiSnipsEdit*
The UltiSnipsEdit command opens a private snippet definition file for the 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 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 UltiSnipsEdit! all public snippet files are taken into account too. If
@ -194,25 +200,32 @@ g:UltiSnipsEditSplit Defines how the edit window is opened. Possible
*g:UltiSnipsSnippetsDir* *g:UltiSnipsSnippetsDir*
g:UltiSnipsSnippetsDir g:UltiSnipsSnippetsDir
Defines the directory private snippet definition Defines the directory where private snippet
files are stored in. For example, if the variable definition files are placed in in.
is set to "~/.vim/mydir/UltiSnips" and the current
'filetype' is "cpp", then :UltiSnipsEdit will open As example, if the current 'filetype' is "cpp" the
"~/.vim/mydir/UltiSnips/cpp.snippets" if file is :UltiSnipsEdit command looks for a file to edit in
not empty, if it's empty :UltiSnipsEdit will see this order:
for non-empty files in directories 1. An existing
g:UltiSnipsSnippetDirectories, if nothing found, g:UltiSnipsSnippetsDir."/cpp.snippets" file
:UltiSnipsEdit will open new file in 2. Find a matching "cpp" snippets file in
g:UltiSnipsSnippetsDir. g:UltiSnipsSnippetDirectories
3. Create a new
g:UltiSnipsSnippetsDir."/cpp.snippets" file
Note that directories named "snippets" are Note that directories named "snippets" are
reserved for snipMate snippets and cannot be used. reserved for snipMate snippets and cannot be used.
Also, this setting does not affect where snippets
are searched for, so it is possible to change this
to opening files that are then not found by
UltiSnips. See |UltiSnips-snippet-search-path| for
details.
*g:UltiSnipsSnippetDirectories* *g:UltiSnipsSnippetDirectories*
g:UltiSnipsSnippetDirectories g:UltiSnipsSnippetDirectories
Defines the directories for looking for snippets. Configures the directories that are searched for
Do not mix up this variable with previous one. snippets. Do not mix up this variable with the
More information about that variable can previous one. See |UltiSnips-how-snippets-are-loaded|.
be found at section |UltiSnips-snippet-search-path|.
*g:UltiSnipsEnableSnipMate* *g:UltiSnipsEnableSnipMate*
g:UltiSnipsEnableSnipMate g:UltiSnipsEnableSnipMate
@ -223,7 +236,8 @@ g:UltiSnipsEnableSnipMate
will look for SnipMate snippets. will look for SnipMate snippets.
*:UltiSnipsAddFiletypes* 3.1.2 UltiSnipsAddFiletypes *:UltiSnipsAddFiletypes*
The UltiSnipsAddFiletypes command allows for explicit merging of other snippet The UltiSnipsAddFiletypes command allows for explicit merging of other snippet
filetypes for the current buffer. For example, if you edit a .rst file but 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 > also want the Lua snippets to be available you can issue the command >
@ -232,7 +246,7 @@ also want the Lua snippets to be available you can issue the command >
using the dotted filetype syntax. Order is important, the first filetype in 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 this list will be the one used for UltiSnipsEdit and the list is
ordered by evaluation priority. Consequently, you might add this to your ordered by evaluation priority. For example you might add this to your
ftplugin/rails.vim > ftplugin/rails.vim >
:UltiSnipsAddFiletypes rails.ruby :UltiSnipsAddFiletypes rails.ruby
@ -250,13 +264,17 @@ The priority will then be rails -> ruby -> programming -> all.
3.2 Triggers *UltiSnips-triggers* 3.2 Triggers *UltiSnips-triggers*
------------ ------------
3.2.1 Trigger key mappings *UltiSnips-trigger-key-mappings*
*g:UltiSnipsExpandTrigger* *g:UltiSnipsListSnippets* *g:UltiSnipsExpandTrigger* *g:UltiSnipsListSnippets*
*g:UltiSnipsJumpForwardTrigger* *g:UltiSnipsJumpBackwardTrigger* *g:UltiSnipsJumpForwardTrigger* *g:UltiSnipsJumpBackwardTrigger*
You can define the keys used to trigger UltiSnips actions by setting global 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 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 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 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: > <c-tab> (and others, like <c-h>) to the running program. The variables with
their default values are: >
g:UltiSnipsExpandTrigger <tab> g:UltiSnipsExpandTrigger <tab>
g:UltiSnipsListSnippets <c-tab> g:UltiSnipsListSnippets <c-tab>
g:UltiSnipsJumpForwardTrigger <c-j> g:UltiSnipsJumpForwardTrigger <c-j>
@ -271,8 +289,7 @@ following to your vimrc file or switching to a plugin like Supertab or
YouCompleteMe. > YouCompleteMe. >
inoremap <c-x><c-k> <c-x><c-k> inoremap <c-x><c-k> <c-x><c-k>
3.2.1 Using your own trigger functions *UltiSnips-trigger-functions* 3.2.2 Using your own trigger functions *UltiSnips-trigger-functions*
--------------------------------------
For advanced users there are four functions that you can map directly to a 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: key and that correspond to some of the triggers previously defined:
@ -316,12 +333,11 @@ then you define your mapping as >
and if the you can't expand or jump from the current location then the and if the you can't expand or jump from the current location then the
alternative function IMAP_Jumpfunc('', 0) is called. alternative function IMAP_Jumpfunc('', 0) is called.
3.2.2 Custom autocommands *UltiSnips-custom-autocommands* 3.2.3 Custom autocommands *UltiSnips-custom-autocommands*
-------------------------
Note Autocommands must not change the buffer in any way. If lines are added, 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 deleted, or modified it will confuse UltiSnips which might scramble your
snippets contents. snippet contents.
*UltiSnipsEnterFirstSnippet* *UltiSnipsExitLastSnippet* *UltiSnipsEnterFirstSnippet* *UltiSnipsExitLastSnippet*
For maximum compatibility with other plug-ins, UltiSnips sets up some special For maximum compatibility with other plug-ins, UltiSnips sets up some special
@ -347,12 +363,11 @@ is entered, and |UltiSnipsExitLastSnippet| will only fire once the last
(outermost) snippet have been exited. (outermost) snippet have been exited.
3.2.4 Direct use of Python API *UltiSnips-use-python-api*
3.2.3 Path to Python module *UltiSnips-python-module-path*
---------------------------
For even more advanced usage, you can directly write python functions using For even more advanced usage, you can directly write python functions using
UltiSnip's python modules. UltiSnip's python modules. This is an internal and therefore unstable API and
not recommended though.
Here is a small example funtion that expands a snippet: > Here is a small example funtion that expands a snippet: >
@ -365,48 +380,8 @@ Here is a small example funtion that expands a snippet: >
return "" return ""
endfunction endfunction
3.3 Snippet Search Path *UltiSnips-snippet-search-path*
-----------------------
UltiSnips snippet definition files are stored in one or more directories. 3.3 Warning About Select Mode Mappings *UltiSnips-warning-smappings*
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: > Vim's help document for |mapmode-s| states: >
@ -435,23 +410,22 @@ complete definition as listed by the |:smap| command. >
let g:UltiSnipsMappingsToIgnore = [ "somePlugin", "otherPlugin" ] let g:UltiSnipsMappingsToIgnore = [ "somePlugin", "otherPlugin" ]
3.5 Functions *UltiSnips-functions* 3.4 Functions *UltiSnips-functions*
------------- -------------
UltiSnips provides some functions for extending core functionality. UltiSnips provides some functions for extending core functionality.
3.5.1 UltiSnips#AddSnippetWithPriority *UltiSnips#AddSnippetWithPriority* 3.4.1 UltiSnips#AddSnippetWithPriority *UltiSnips#AddSnippetWithPriority*
The first function is UltiSnips#AddSnippetWithPriority(trigger, value, description, The first function is UltiSnips#AddSnippetWithPriority(trigger, value, description,
options, filetyp, priority). It adds a new snippet with the provided trigger, value, options, filetyp, priority). It adds a new snippet to the current list of
description, and options to the current list of snippets. See snippets. See |UltiSnips-authoring-snippets| for details most of the function
|UltiSnips-syntax| for details on the meaning of the function arguments. The arguments. The priority is a number that defines which snippet should be
Priority is a number that defines which snippet should be preferred over preferred over others. See the priority keyword in |UltiSnips-add-snippets|.
others. See the priority keyword in|UltiSnips-add-snippets|.
3.5.2 UltiSnips#Anon *UltiSnips#Anon* 3.4.2 UltiSnips#Anon *UltiSnips#Anon*
The second function is UltiSnips#Anon(value, ...). It expands an anonymous The second function is UltiSnips#Anon(value, ...). It expands an anonymous
snippet. Anonymous snippets are defined on the spot, expanded and immediately snippet. Anonymous snippets are defined on the spot, expanded and immediately
@ -472,41 +446,24 @@ This expands the snippet whenever two $ signs are typed.
Note: The right-hand side of the mapping starts with an immediate retype of 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. the '$$' trigger and passes '$$' to the function as the trigger argument.
This is required in order for UltiSnips to have access to the characters This is required in order for UltiSnips to have access to the characters
typed so it can determine if the trigger matches or not. typed so it can determine if the trigger matches or not. A more elegant way of
creating such a snippet could be to use |UltiSnips-autotrigger|.
3.5.3 UltiSnips#SnippetsInCurrentScope *UltiSnips#SnippetsInCurrentScope* 3.4.3 UltiSnips#SnippetsInCurrentScope *UltiSnips#SnippetsInCurrentScope*
A third function is UltiSnips#SnippetsInCurrentScope which is the equivalent UltiSnips#SnippetsInCurrentScope returns a vim dictionary with the snippets
of snipmate GetSnipsInCurrentScope function. whose trigger matches the current word. If you need all snippets information
for the current buffer, you can simply pass 1 (which means all) as first
This function simply returns a vim dictionary with the snippets whose trigger argument of this function, and use a global variable g:current_ulti_dict_info
matches the current word. If you need all snippets information of current to get the result (see example below).
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 This function does not add any new functionality to ultisnips directly but
allows to use third party plugins to integrate the current available snippets. allows to use third party plugins to integrate the current available snippets.
For example, all completion plugins that integrate with UltiSnips use this
function.
An example of such third party plugin is SnippetCompleteSnipMate which uses Another example on how to use this function consider the following function
the function GetSnipsInCurrentScope to integrate the current available and mapping definition:
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() function! ExpandPossibleShorterSnippet()
if len(UltiSnips#SnippetsInCurrentScope()) == 1 "only one candidate... if len(UltiSnips#SnippetsInCurrentScope()) == 1 "only one candidate...
@ -524,8 +481,8 @@ 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 snippets whose trigger matches lor then hitting <C-L> will expand to whatever
lorem expands to. lorem expands to.
A third example on how to use this function to extract all snippets of One more example on how to use this function to extract all snippets available
current buffer: > in the current buffer: >
function! GetAllSnippets() function! GetAllSnippets()
call UltiSnips#SnippetsInCurrentScope(1) call UltiSnips#SnippetsInCurrentScope(1)
@ -542,11 +499,7 @@ function! GetAllSnippets()
return list return list
endfunction endfunction
The new variable g:current_ulti_dict_info is made to avoid confilct with 3.5 Warning about missing python support *UltiSnips-python-warning*
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 When UltiSnips is loaded, it will check that the running Vim was compiled with
@ -562,17 +515,48 @@ 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. systems where some of them may not have Vim compiled with python support.
============================================================================= =============================================================================
4. Syntax *UltiSnips-syntax* 4. Authoring snippets *UltiSnips-authoring-snippets*
This chapter describes how to write your own snippets and snippet definition 4.1 Basics *UltiSnips-basics*
syntax. Examples are used to help illustrate. ----------
4.1.1 How snippets are loaded *UltiSnips-how-snippets-are-loaded*
4.1 Adding Snippets *UltiSnips-adding-snippets* Snippet definition files are stored in snippet directories. The main
------------------- controlling variable for where these directories are searched for is the
list variable, set by default to >
See |UltiSnips-snippet-search-path| for an explanation of where directories let g:UltiSnipsSnippetDirectories=["UltiSnips"]
with snippet definitions should be located.
Note that "snippets" is reserved for snipMate snippets and cannot be used in
this list.
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 `~/.vim/mycoolsnippets`and you want to
make use of the UltiSnips snippets that come with other plugins, 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"]
If the list has only one entry that is an absolute path, UltiSnips will not
iterate through &runtimepath but only look in this one directory for snippets.
This can lead to significant speedup. This means you will miss out on snippets
that are shipped with third party plugins. You'll need to copy them into this
directory manually.
An example configuration could be: >
let g:UltiSnipsSnippetDirectories=[$HOME.'/.vim/UltiSnips']
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.
Using a strategy similar to how Vim detects |ftplugins|, UltiSnips iterates Using a strategy similar to how Vim detects |ftplugins|, UltiSnips iterates
over the snippet definition directories looking for files with names of the over the snippet definition directories looking for files with names of the
@ -588,10 +572,10 @@ snippet filenames and their associated filetype.
c_my.snippets c c_my.snippets c
c/a c c/a c
c/b.snippets c c/b.snippets c
all.snippets *all all.snippets all
all/a.snippets *all all/a.snippets all
* The 'all' filetype is unique. It represents snippets available for use when The 'all' filetype is unique. It represents snippets available for use when
editing any document regardless of the filetype. A date insertion snippet, for editing any document regardless of the filetype. A date insertion snippet, for
example, would fit well in the all.snippets file. example, would fit well in the all.snippets file.
@ -600,6 +584,8 @@ 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 UltiSnips will search for and activate snippets for both the cuda and cpp
filetypes. filetypes.
4.1.2 Basic syntax *UltiSnips-basic-syntax*
The snippets file syntax is simple. All lines starting with a # character are The snippets file syntax is simple. All lines starting with a # character are
considered comments. Comments are ignored by UltiSnips. Use them to document considered comments. Comments are ignored by UltiSnips. Use them to document
snippets. snippets.
@ -627,10 +613,10 @@ the ones with the highest priority. For example, all shipped snippets have a
priority < 0, so that user defined snippets always overwrite shipped snippets. priority < 0, so that user defined snippets always overwrite shipped snippets.
A line beginning with the keyword 'snippet' marks the beginning of snippet A line beginning with the keyword 'snippet' marks the beginning of a snippet
definition and a line starting with the keyword 'endsnippet' marks the end. 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 The snippet definition is placed between the lines. Here is a snippet of an
'if' statement for the Unix shell (sh) filetype. 'if' statement for the Unix shell (sh) filetype. >
snippet if "if ... then (if)" snippet if "if ... then (if)"
if ${2:[[ ${1:condition} ]]}; then if ${2:[[ ${1:condition} ]]}; then
@ -640,12 +626,12 @@ The snippet definition is placed between the lines. Here is a snippet of an
The start line takes the following form: > The start line takes the following form: >
snippet tab_trigger [ "description" [ options ] ] snippet trigger_word [ "description" [ options ] ]
The tab_trigger is required, but the description and options are optional. The trigger_word is required, but the description and options are optional.
The 'tab_trigger' is the word or string sequence used to trigger the snippet. The 'trigger_word' 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 Generally a single word is used but the trigger_word can include spaces. If you
wish to include spaces, you must wrap the tab trigger in quotes. > wish to include spaces, you must wrap the tab trigger in quotes. >
snippet "tab trigger" [ "description" [ options ] ] snippet "tab trigger" [ "description" [ options ] ]
@ -670,7 +656,10 @@ 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 match, UltiSnips displays a list of the matching snippets with their
descriptions. The user then selects the snippet they want. descriptions. The user then selects the snippet they want.
4.1.1 Snippet Options: *UltiSnips-snippet-options*
4.1.3 Snippet Options: *UltiSnips-snippet-options*
The 'options' control the behavior of the snippet. Options are indicated by The 'options' control the behavior of the snippet. Options are indicated by
single characters. The 'options' characters for a snippet are combined into single characters. The 'options' characters for a snippet are combined into
@ -711,7 +700,7 @@ The options currently supported are: >
indentation settings. (For example, if 'expandtab' is set, the tab is indentation settings. (For example, if 'expandtab' is set, the tab is
replaced with spaces.) If this option is set, UltiSnips will ignore the 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 Vim settings and insert the tab characters as is. This option is useful
for snippets involved with tab delimited formats, for example. for snippets involved with tab delimited formats.
s Remove whitespace immediately before the cursor at the end of a line 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 before jumping to the next tabstop. This is useful if there is a
@ -722,10 +711,10 @@ The options currently supported are: >
Without this option empty lines in snippets definition will have Without this option empty lines in snippets definition will have
indentation too. indentation too.
e Context snippets - With this option expansion of snippet can be e Custom context snippet - With this option expansion of snippet can be
controlled not only by previous characters in line, but by any given controlled not only by previous characters in line, but by any given
python expression. This option can be specified along with other python expression. This option can be specified along with other
options, like 'b'. See |UltiSnips-context-snippets| for more info. options, like 'b'. See |UltiSnips-custom-context-snippets| for more info.
A Snippet will be triggered automatically, when condition matches. A Snippet will be triggered automatically, when condition matches.
See |UltiSnips-autotrigger| for more info. See |UltiSnips-autotrigger| for more info.
@ -738,7 +727,7 @@ When parsing snippet files, UltiSnips chops the trailing newline character
from the 'endsnippet' end line. from the 'endsnippet' end line.
4.1.2 Character Escaping: *UltiSnips-character-escaping* 4.1.4 Character Escaping: *UltiSnips-character-escaping*
In snippet definitions, the characters '`', '{', '$' and '\' have special In snippet definitions, the characters '`', '{', '$' and '\' have special
meaning. If you want to insert one of these characters literally, escape them meaning. If you want to insert one of these characters literally, escape them
@ -800,7 +789,7 @@ The ${VISUAL} placeholder can also define a transformation (see
Here is a simple example illustrating a visual transformation. The snippet Here is a simple example illustrating a visual transformation. The snippet
will take selected text, replace every instance of "should" within it with will take selected text, replace every instance of "should" within it with
"is" , and wrap the result in tags. "is", and wrap the result in tags.
------------------- SNIP ------------------- ------------------- SNIP -------------------
snippet t snippet t
@ -884,10 +873,9 @@ 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 python shebang '#!/usr/bin/python', but using the '!p' format comes with some
predefined objects and variables, which can simplify and shorten code. For predefined objects and variables, which can simplify and shorten code. For
example, a 'snip' object instance is implied in python code. Python code using 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 the '!p' indicator differs also in another way. Generally when a snippet is
expanded the standard output of code replaces the code. With python code the 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 value of the 'snip.rv' property replaces the code. Standard output is ignored.
output is ignored.
The variables automatically defined in python code are: > The variables automatically defined in python code are: >
@ -895,8 +883,12 @@ The variables automatically defined in python code are: >
path - The complete path to the current file path - The complete path to the current file
t - The values of the placeholders, t[1] is the text of ${1}, etc. t - The values of the placeholders, t[1] is the text of ${1}, etc.
snip - UltiSnips.TextObjects.SnippetUtil object instance. Has methods snip - UltiSnips.TextObjects.SnippetUtil object instance. Has methods
that simplify indentation handling. that simplify indentation handling and owns the string that
context - Result of context condition. See |UltiSnips-context-snippets|. should be inserted for the snippet.
context - Result of context condition. See |UltiSnips-custom-context-snippets|.
match - Only in regular expression triggered snippets. This is the return
value of the match of the regular expression. See
http://docs.python.org/library/re.html#match-objects
The 'snip' object provides the following methods: > The 'snip' object provides the following methods: >
@ -934,8 +926,7 @@ The 'snip' object provides some properties as well: >
is only done once. This deprecates the "cur" variable. is only done once. This deprecates the "cur" variable.
snip.v: snip.v:
Data related to the ${VISUAL} placeholder. The property has two Data related to the ${VISUAL} placeholder. This has two attributes:
attributes:
snip.v.mode ('v', 'V', '^V', see |visual-mode| ) snip.v.mode ('v', 'V', '^V', see |visual-mode| )
snip.v.text The text that was selected. snip.v.text The text that was selected.
@ -1083,7 +1074,7 @@ The syntax for a tabstop is the dollar sign followed by a number, for example,
'$1'. Tabstops start at number 1 and are followed in sequential order. The '$1'. Tabstops start at number 1 and are followed in sequential order. The
'$0' tabstop is a special tabstop. It is always the last tabstop in the '$0' tabstop is a special tabstop. It is always the last tabstop in the
snippet no matter how many tabstops are defined. If there is no '$0' defined, snippet no matter how many tabstops are defined. If there is no '$0' defined,
'$0' tabstop will be defined at the end of snippet. '$0' tabstop will be defined at the end of the snippet.
Here is a simple example. Here is a simple example.
@ -1102,9 +1093,9 @@ Yours sincerely,
Paul Paul
You can use <c-j> to jump to the next tabstop, and <c-k> to jump to the You can use <c-j> to jump to the next tabstop, and <c-k> to jump to the
previous. The <Tab> key was not used for jumping forward because many people previous. The <Tab> key was not used for jumping forward because it is
(myself included) use <Tab> for completion. See |UltiSnips-triggers| for commonly used for completion. See |UltiSnips-triggers| for help on defining
help on defining different keys for tabstops. different keys for motions.
It is often useful to have some default text for a tabstop. The default text It is often useful to have some default text for a tabstop. The default text
may be a value commonly used for the variable component, or it may be a word may be a value commonly used for the variable component, or it may be a word
@ -1373,7 +1364,7 @@ printf("A is: %s\n", A); // End of line
There are many more examples of what can be done with transformations in the There are many more examples of what can be done with transformations in the
bundled snippets. vim-snippets repo.
4.8 Clearing snippets *UltiSnips-clearing-snippets* 4.8 Clearing snippets *UltiSnips-clearing-snippets*
@ -1408,22 +1399,23 @@ clearsnippets trigger1 trigger2
------------------- SNAP ------------------- ------------------- SNAP -------------------
4.9 Context snippets *UltiSnips-context-snippets* 4.9 Custom context snippets *UltiSnips-custom-context-snippets*
Context snippets can be enabled by using 'e' option in snippet definition. Custom context snippets can be enabled by using the 'e' option in the snippet
definition.
In that case snippet should be defined using this syntax: > In that case snippet should be defined using this syntax: >
snippet tab_trigger "description" "expression" options snippet trigger_word "description" "expression" options
Context can be defined using special header using this syntax: > The context can be defined using a special header: >
context "expression" context "python_expression"
snippet tab_trigger "description" options snippet trigger_word "description" options
The 'expression' can be any python expression. If 'expression' evaluates to The 'expression' can be any python expression. If 'expression' evaluates to
'True', then this snippet will be chosen for expansion. The 'expression' must 'True', then this snippet will be eligible for expansion. The 'expression'
be wrapped with double-quotes. must be wrapped with double-quotes.
The following python modules are automatically imported into the scope before The following python modules are automatically imported into the scope before
'expression' is evaluated: 're', 'os', 'vim', 'string', 'random'. 'expression' is evaluated: 're', 'os', 'vim', 'string', 'random'.
@ -1459,8 +1451,8 @@ endsnippet
That snippet will expand to 'return err' only if the previous line is starting That snippet will expand to 'return err' only if the previous line is starting
from 'if err' prefix. from 'if err' prefix.
Note: context snippets prioritized over non-context ones. It makes possible to Note: custom context snippets are prioritized over other snippets. It makes possible
use non-context snippets as fallback, if no context matched: to use other snippets as a fallback if no context can be matched:
------------------- SNIP ------------------- ------------------- SNIP -------------------
snippet i "if ..." b snippet i "if ..." b
@ -1476,8 +1468,8 @@ if err != nil {
endsnippet endsnippet
------------------- SNAP ------------------- ------------------- SNAP -------------------
That snippet will expand into 'if err != nil' if previous line will That snippet will expand into 'if err != nil' if the previous line will match
match 'err :=' prefix, otherwise the default 'if' snippet will be expanded. 'err :=' prefix, otherwise the default 'if' snippet will be expanded.
It's a good idea to move context conditions to a separate module, so it can be It's a good idea to move context conditions to a separate module, so it can be
used by other UltiSnips users. In that case, module should be imported used by other UltiSnips users. In that case, module should be imported
@ -1516,8 +1508,8 @@ That snippet will expand to 'var1 +=' after line, which begins from 'var1 :='.
*UltiSnips-capture-placeholder* *UltiSnips-capture-placeholder*
You can capture placeholder text from previous snippet by using following You can capture placeholder text from the previous snippet by using the
trick: following trick:
------------------- SNIP ------------------- ------------------- SNIP -------------------
snippet = "desc" "snip.last_placeholder" Ae snippet = "desc" "snip.last_placeholder" Ae
`!p snip.rv = snip.context.current_text` == nil `!p snip.rv = snip.context.current_text` == nil
@ -1532,27 +1524,27 @@ tabstop value following by ' == nil'.
4.10 Snippets actions *UltiSnips-snippet-actions* 4.10 Snippets actions *UltiSnips-snippet-actions*
--------------------- ---------------------
Snippet actions is an arbitrary python code which can be executed at specific A snippet action is an arbitrary python code which can be executed at specific
points in lifetime of the snippet. points in the lifetime of a snippet expansion.
There are three types of actions: There are three types of actions:
* Pre-expand - invoked just after trigger condition was matched, but before * Pre-expand - invoked just after trigger condition was matched, but before
snippet actually expanded; snippet actually expanded;
* Post-expand - invoked after snippet was expanded and interpolations * Post-expand - invoked after snippet was expanded and interpolations
was applied for the first time, but before jump on the first placeholder. were applied for the first time, but before jump on the first placeholder.
* Jump - invoked just after jump to the next/prev placeholder. * Jump - invoked just after a jump to the next/prev placeholder.
Specified code will be evaluated at stages defined above and same global Specified code will be evaluated at stages defined above and same global
variables and modules will be available that are stated in variables and modules will be available that are stated in
the |UltiSnips-context-snippets| section. the |UltiSnips-custom-context-snippets| section.
*UltiSnips-buffer-proxy* *UltiSnips-buffer-proxy*
Note: special variable called 'snip.buffer' should be used for all buffer Note: special variable called 'snip.buffer' should be used for all buffer
modifications. Not 'vim.current.buffer' and not 'vim.command("...")', because modifications. Not 'vim.current.buffer' and not 'vim.command("...")', because
of in that case UltiSnips will not be able to track changes in buffer from in that case UltiSnips will not be able to track changes to the buffer
actions. correctly.
'snip.buffer' has the same interface as 'vim.current.window.buffer'. 'snip.buffer' has the same interface as 'vim.current.window.buffer'.
@ -1607,7 +1599,7 @@ endsnippet
Post-expand actions can be used to perform some actions based on the expanded Post-expand actions can be used to perform some actions based on the expanded
snippet text. Some cases are: code style formatting (e.g. inserting newlines snippet text. Some cases are: code style formatting (e.g. inserting newlines
before and after method declaration), apply actions depending on python before and after method declaration), and apply actions depending on python
interpolation result. interpolation result.
Post-expand action declared as follows: > Post-expand action declared as follows: >
@ -1706,7 +1698,7 @@ endsnippet
4.11 Autotrigger *UltiSnips-autotrigger* 4.11 Autotrigger *UltiSnips-autotrigger*
---------------- ----------------
Note: vim should be newer than 7.4.214 to support this feature. Note: vim must be newer than 7.4.214 to support this feature.
Many language constructs can occur only at specific places, so it's Many language constructs can occur only at specific places, so it's
possible to use snippets without manually triggering them. possible to use snippets without manually triggering them.
@ -1715,13 +1707,13 @@ Snippet can be marked as autotriggered by specifying 'A' option in the snippet
definition. definition.
After snippet is defined as being autotriggered, snippet condition will be After snippet is defined as being autotriggered, snippet condition will be
checked on every typed character and if condition matches, then snippet will checked on every typed character and if condition matches, then the snippet
be triggered. will be triggered.
*Warning:* using of this feature can lead to significant vim slowdown. If you *Warning:* using of this feature might lead to significant vim slowdown. If
discovered that, report an issue to the github.com/SirVer/UltiSnips. you discovered that, please report an issue.
Consider following snippets, that can be usefull in Go programming: Consider following useful Go snippets:
------------------- SNIP ------------------- ------------------- SNIP -------------------
snippet "^p" "package" rbA snippet "^p" "package" rbA
package ${1:main} package ${1:main}
@ -1753,7 +1745,7 @@ pull request.
snipMate - UltiSnips is a drop-in replacement for snipMate. It has many more snipMate - UltiSnips is a drop-in replacement for snipMate. It has many more
features, so porting snippets is still a good idea, but switching has low features, so porting snippets is still a good idea, but switching has low
friction now. UltiSnips is trying hard to truly emulate snipMate, for example friction. UltiSnips is trying hard to truly emulate snipMate, for example
recursive tabstops are not supported in snipMate snippets (but of course in recursive tabstops are not supported in snipMate snippets (but of course in
UltiSnips snippets). UltiSnips snippets).
@ -1790,15 +1782,15 @@ to Supertab for expansion.
UltiSnips allows other plugins to add new snippets on the fly. Since UltiSnips UltiSnips allows other plugins to add new snippets on the fly. Since UltiSnips
is written in python, the integration is also on a python basis. A small is written in python, the integration is also on a python basis. A small
example can be found in `test.py`, search for AddNewSnippetSource. Please example can be found in `test/test_UltiSnipsFunc.py`, search for
contact us on github if you integrate UltiSnips with your plugin so it can be AddNewSnippetSource. Please contact us on github if you integrate UltiSnips
listed in the docs. with your plugin so it can be listed in the docs.
============================================================================= =============================================================================
6. FAQ *UltiSnips-FAQ* 6. FAQ *UltiSnips-FAQ*
Q: Do I have to call UltiSnips#ExpandSnippet() to check if a snippet is Q: Do I have to call UltiSnips#ExpandSnippet() to check if a snippet is
expandable ? Is there instead an analog of neosnippet#expandable ? expandable ? Is there instead an analog of neosnippet#expandable ?
A: Yes there is, try A: Yes there is, try
function UltiSnips#IsExpandable() function UltiSnips#IsExpandable()
@ -1823,8 +1815,9 @@ https://github.com/sirver/ultisnips/issues
8. Contributors *UltiSnips-contributors* 8. Contributors *UltiSnips-contributors*
UltiSnips has been started and maintained from Jun 2009 - Dec 2015 by Holger UltiSnips has been started and maintained from Jun 2009 - Dec 2015 by Holger
Rapp (@SirVer, SirVer@gmx.de). It is now maintained by Stanislav Seletskiy Rapp (@SirVer, SirVer@gmx.de). Up to April 2018 it was maintained by Stanislav
(@seletskiy). Seletskiy (@seletskiy). Now, it is maintained by a growing set of
contributors.
This is the list of contributors pre-git in chronological order. For a full This is the list of contributors pre-git in chronological order. For a full
list of contributors take the union of this set and the authors according to list of contributors take the union of this set and the authors according to