1876 lines
75 KiB
Plaintext
1876 lines
75 KiB
Plaintext
*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> ->
|
|
\begin{center}
|
|
|
|
\end{center}
|
|
|
|
The second form is a variation of the first; both produce the same result,
|
|
but it illustrates how regular expression grouping works. Using regular
|
|
expressions in this manner has some drawbacks:
|
|
1. If you use the <Tab> key for both expanding snippets and completion then
|
|
if you typed "be form<Tab>" expecting the completion "be formatted", you
|
|
would end up with the above SNAP instead, not what you want.
|
|
2. The snippet is harder to read.
|
|
|
|
The biggest advantage, however, is that you can create snippets that take into
|
|
account the text preceding a "trigger". This way, you can use it to create
|
|
postfix snippets, which are popular in some IDEs.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet "(\w+).par" "Parenthesis (postfix)" r
|
|
(`!p snip.rv = match.group(1)`$1)$0
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
something.par<tab> ->
|
|
(something)
|
|
|
|
------------------- SNIP -------------------
|
|
snippet "([^\s].*)\.return" "Return (postfix)" r
|
|
return `!p snip.rv = match.group(1)`$0
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
value.return<tab> ->
|
|
return value
|
|
|
|
|
|
4.4.4 Global Snippets: *UltiSnips-globals*
|
|
|
|
Global snippets provide a way to reuse common code in multiple snippets.
|
|
Currently, only python code is supported. The result of executing the contents
|
|
of a global snippet is put into the globals of each python block in the
|
|
snippet file. To create a global snippet, use the keyword 'global' in place of
|
|
'snippet', and for python code, you use '!p' for the trigger. For example, the
|
|
following snippet produces the same output as the last example . However, with
|
|
this syntax the 'upper_right' snippet can be reused by other snippets.
|
|
|
|
------------------- SNIP -------------------
|
|
global !p
|
|
def upper_right(inp):
|
|
return (75 - 2 * len(inp))*' ' + inp.upper()
|
|
endglobal
|
|
|
|
snippet wow
|
|
${1:Text}`!p snip.rv = upper_right(t[1])`
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
wow<tab>Hello World ->
|
|
Hello World HELLO WORLD
|
|
|
|
Python global functions can be stored in a python module and then imported.
|
|
This makes global functions easily accessible to all snippet files. Since Vim
|
|
7.4 you can just drop python files into ~/.vim/pythonx and import them
|
|
directly inside your snippets. For example to use
|
|
~/.vim/pythonx/my_snippets_helpers.py >
|
|
|
|
global !p
|
|
from my_snippet_helpers import *
|
|
endglobal
|
|
|
|
|
|
4.5 Tabstops and Placeholders *UltiSnips-tabstops* *UltiSnips-placeholders*
|
|
-----------------------------
|
|
|
|
Snippets are used to quickly insert reused text into a document. Often the
|
|
text has a fixed structure with variable components. Tabstops are used to
|
|
simplify modifying the variable content. With tabstops you can easily place
|
|
the cursor at the point of the variable content, enter the content you want,
|
|
then jump to the next variable component, enter that content, and continue
|
|
until all the variable components are complete.
|
|
|
|
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
|
|
'$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,
|
|
'$0' tabstop will be defined at the end of snippet.
|
|
|
|
Here is a simple example.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet letter
|
|
Dear $1,
|
|
$0
|
|
Yours sincerely,
|
|
$2
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
letter<tab>Ben<c-j>Paul<c-j>Thanks for suggesting UltiSnips!->
|
|
Dear Ben,
|
|
Thanks for suggesting UltiSnips!
|
|
Yours sincerely,
|
|
Paul
|
|
|
|
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
|
|
(myself included) use <Tab> for completion. See |UltiSnips-triggers| for
|
|
help on defining different keys for tabstops.
|
|
|
|
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
|
|
or phrase that reminds you what is expected for the variable component. To
|
|
include default text, the syntax is '${1:value}'.
|
|
|
|
The following example illustrates a snippet for the shell 'case' statement.
|
|
The tabstops use default values to remind the user of what value is expected.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet case
|
|
case ${1:word} in
|
|
${2:pattern} ) $0;;
|
|
esac
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
case<tab>$option<c-j>-v<c-j>verbose=true
|
|
case $option in
|
|
-v ) verbose=true;;
|
|
esac
|
|
|
|
|
|
Sometimes it is useful to have a tabstop within a tabstop. To do this, simply
|
|
include the nested tabstop as part of the default text. Consider the following
|
|
example illustrating an HTML anchor snippet.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet a
|
|
<a href="${1:http://www.${2:example.com}}"</a>
|
|
$0
|
|
</a>
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
When this snippet is expanded, the first tabstop has a default value of
|
|
'http://www.example.com'. If you want the 'http://' schema, jump to the next
|
|
tabstop. It has a default value of 'example.com'. This can be replaced by
|
|
typing whatever domain you want.
|
|
|
|
a<tab><c-j>google.com<c-j>Google ->
|
|
<a href="http://www.google.com">
|
|
Google
|
|
</a>
|
|
|
|
If at the first tabstop you want a different url schema or want to replace the
|
|
default url with a named anchor, '#name', for example, just type the value you
|
|
want.
|
|
|
|
a<tab>#top<c-j>Top ->
|
|
<a href="#top">
|
|
Top
|
|
</a>
|
|
|
|
In the last example, typing any text at the first tabstop replaces the default
|
|
value, including the second tabstop, with the typed text. So the second
|
|
tabstop is essentially deleted. When a tabstop jump is triggered, UltiSnips
|
|
moves to the next remaining tabstop '$0'. This feature can be used
|
|
intentionally as a handy way for providing optional tabstop values to the
|
|
user. Here is an example to illustrate.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet a
|
|
<a href="$1"${2: class="${3:link}"}>
|
|
$0
|
|
</a>
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
Here, '$1' marks the first tabstop. It is assumed you always want to add a
|
|
value for the 'href' attribute. After entering the url and pressing <c-j>, the
|
|
snippet will jump to the second tabstop, '$2'. This tabstop is optional. The
|
|
default text is ' class="link"'. You can press <c-j> to accept the tabstop,
|
|
and the snippet will jump to the third tabstop, '$3', and you can enter the
|
|
class attribute value, or, at the second tabstop you can press the backspace
|
|
key thereby replacing the second tabstop default with an empty string,
|
|
essentially removing it. In either case, continue by pressing <c-j> and the
|
|
snippet will jump to the final tabstop inside the anchor.
|
|
|
|
a<tab>http://www.google.com<c-j><c-j>visited<c-j>Google ->
|
|
<a href="http://www.google.com" class="visited">
|
|
Google
|
|
</a>
|
|
|
|
a<tab>http://www.google.com<c-j><BS><c-j>Google ->
|
|
<a href="http://www.google.com">
|
|
Google
|
|
</a>
|
|
|
|
The default text of tabstops can also contain mirrors, transformations or
|
|
interpolation.
|
|
|
|
|
|
4.6 Mirrors *UltiSnips-mirrors*
|
|
-----------
|
|
|
|
Mirrors repeat the content of a tabstop. During snippet expansion when you
|
|
enter the value for a tabstop, all mirrors of that tabstop are replaced with
|
|
the same value. To mirror a tabstop simply insert the tabstop again using the
|
|
"dollar sign followed by a number" syntax, e.g., '$1'.
|
|
|
|
A tabstop can be mirrored multiple times in one snippet, and more than one
|
|
tabstop can be mirrored in the same snippet. A mirrored tabstop can have a
|
|
default value defined. Only the first instance of the tabstop need have a
|
|
default value. Mirrored tabstop will take on the default value automatically.
|
|
|
|
Mirrors are handy for start-end tags, for example, TeX 'begin' and 'end' tag
|
|
labels, XML and HTML tags, and C code #ifndef blocks. Here are some snippet
|
|
examples.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet env
|
|
\begin{${1:enumerate}}
|
|
$0
|
|
\end{$1}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
env<tab>itemize ->
|
|
\begin{itemize}
|
|
|
|
\end{itemize}
|
|
|
|
------------------- SNIP -------------------
|
|
snippet ifndef
|
|
#ifndef ${1:SOME_DEFINE}
|
|
#define $1
|
|
$0
|
|
#endif /* $1 */
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
ifndef<tab>WIN32 ->
|
|
#ifndef WIN32
|
|
#define WIN32
|
|
|
|
#endif /* WIN32 */
|
|
|
|
|
|
4.7 Transformations *UltiSnips-transformations*
|
|
-------------------
|
|
|
|
Note: Transformations are a bit difficult to grasp so this chapter is divided
|
|
into two sections. The first describes transformations and their syntax, and
|
|
the second illustrates transformations with demos.
|
|
|
|
Transformations are like mirrors but instead of just copying text from the
|
|
original tabstop verbatim, a regular expression is matched to the content of
|
|
the referenced tabstop and a transformation is then applied to the matched
|
|
pattern. The syntax and functionality of transformations in UltiSnips follow
|
|
very closely to TextMate transformations.
|
|
|
|
A transformation has the following syntax: >
|
|
${<tab_stop_no/regular_expression/replacement/options}
|
|
|
|
The components are defined as follows: >
|
|
tab_stop_no - The number of the tabstop to reference
|
|
regular_expression - The regular expression the value of the referenced
|
|
tabstop is matched on
|
|
replacement - The replacement string, explained in detail below
|
|
options - Options for the regular expression
|
|
|
|
The options can be any combination of >
|
|
g - global replace
|
|
By default, only the first match of the regular expression is
|
|
replaced. With this option all matches are replaced.
|
|
i - case insensitive
|
|
By default, regular expression matching is case sensitive. With this
|
|
option, matching is done without regard to case.
|
|
m - multiline
|
|
By default, the '^' and '$' special characters only apply to the
|
|
start and end of the entire string; so if you select multiple lines,
|
|
transformations are made on them entirely as a whole single line
|
|
string. With this option, '^' and '$' special characters match the
|
|
start or end of any line within a string ( separated by newline
|
|
character - '\n' ).
|
|
a - ascii conversion
|
|
By default, transformation are made on the raw utf-8 string. With
|
|
this option, matching is done on the corresponding ASCII string
|
|
instead, for example 'à' will become 'a'.
|
|
This option required the python package 'unidecode'.
|
|
|
|
The syntax of regular expressions is beyond the scope of this document. Python
|
|
regular expressions are used internally, so the python 're' module can be used
|
|
as a guide. See http://docs.python.org/library/re.html.
|
|
|
|
The syntax for the replacement string is unique. The next paragraph describes
|
|
it in detail.
|
|
|
|
|
|
4.7.1 Replacement String: *UltiSnips-replacement-string*
|
|
|
|
The replacement string can contain $no variables, e.g., $1, which reference
|
|
matched groups in the regular expression. The $0 variable is special and
|
|
yields the whole match. The replacement string can also contain special escape
|
|
sequences: >
|
|
\u - Uppercase next letter
|
|
\l - Lowercase next letter
|
|
\U - Uppercase everything till the next \E
|
|
\L - Lowercase everything till the next \E
|
|
\E - End upper or lowercase started with \L or \U
|
|
\n - A newline
|
|
\t - A literal tab
|
|
|
|
Finally, the replacement string can contain conditional replacements using the
|
|
syntax (?no:text:other text). This reads as follows: if the group $no has
|
|
matched, insert "text", otherwise insert "other text". "other text" is
|
|
optional and if not provided defaults to the empty string, "". This feature
|
|
is very powerful. It allows you to add optional text into snippets.
|
|
|
|
|
|
4.7.2 Demos: *UltiSnips-demos*
|
|
|
|
Transformations are very powerful but often the syntax is convoluted.
|
|
Hopefully the demos below help illustrate transformation features.
|
|
|
|
Demo: Uppercase one character
|
|
------------------- SNIP -------------------
|
|
snippet title "Title transformation"
|
|
${1:a text}
|
|
${1/\w+\s*/\u$0/}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
title<tab>big small ->
|
|
big small
|
|
Big small
|
|
|
|
|
|
Demo: Uppercase one character and global replace
|
|
------------------- SNIP -------------------
|
|
snippet title "Titlelize in the Transformation"
|
|
${1:a text}
|
|
${1/\w+\s*/\u$0/g}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
title<tab>this is a title ->
|
|
this is a title
|
|
This Is A Title
|
|
|
|
|
|
Demo: ASCII transformation
|
|
------------------- SNIP -------------------
|
|
snippet ascii "Replace non ascii chars"
|
|
${1: an accentued text}
|
|
${1/.*/$0/a}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
ascii<tab>à la pêche aux moules
|
|
à la pêche aux moules
|
|
a la peche aux moules
|
|
|
|
|
|
Demo: Regular expression grouping
|
|
This is a clever c-like printf snippet, the second tabstop is only shown
|
|
when there is a format (%) character in the first tabstop.
|
|
|
|
------------------- SNIP -------------------
|
|
snippet printf
|
|
printf("${1:%s}\n"${1/([^%]|%%)*(%.)?.*/(?2:, :\);)/}$2${1/([^%]|%%)*(%.)?.*/(?2:\);)/}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
printf<tab>Hello<c-j> // End of line ->
|
|
printf("Hello\n"); // End of line
|
|
|
|
But
|
|
printf<tab>A is: %s<c-j>A<c-j> // End of line ->
|
|
printf("A is: %s\n", A); // End of line
|
|
|
|
|
|
There are many more examples of what can be done with transformations in the
|
|
bundled snippets.
|
|
|
|
|
|
4.8 Clearing snippets *UltiSnips-clearing-snippets*
|
|
|
|
To remove snippets for the current file type, use the 'clearsnippets'
|
|
directive.
|
|
|
|
------------------- SNIP -------------------
|
|
clearsnippets
|
|
------------------- SNAP -------------------
|
|
|
|
'clearsnippets' removes all snippets with a priority lower than the current
|
|
one. For example, the following cleares all snippets that have priority <= 1,
|
|
even though the example snippet is defined after the 'clearsnippets'.
|
|
|
|
------------------- SNIP -------------------
|
|
priority 1
|
|
clearsnippets
|
|
|
|
priority -1
|
|
snippet example "Cleared example"
|
|
This will never be expanded.
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
To clear one or more specific snippet, provide the triggers of the snippets as
|
|
arguments to the 'clearsnippets' command. The following example will clear the
|
|
snippets 'trigger1' and 'trigger2'.
|
|
|
|
------------------- SNIP -------------------
|
|
clearsnippets trigger1 trigger2
|
|
------------------- SNAP -------------------
|
|
|
|
|
|
4.9 Context snippets *UltiSnips-context-snippets*
|
|
|
|
Context snippets can be enabled by using 'e' option in snippet definition.
|
|
|
|
In that case snippet should be defined using this syntax: >
|
|
|
|
snippet tab_trigger "description" "expression" options
|
|
|
|
Context can be defined using special header using this syntax: >
|
|
|
|
context "expression"
|
|
snippet tab_trigger "description" options
|
|
|
|
The 'expression' can be any python expression. If 'expression' evaluates to
|
|
'True', then this snippet will be chosen for expansion. The 'expression' must
|
|
be wrapped with double-quotes.
|
|
|
|
The following python modules are automatically imported into the scope before
|
|
'expression' is evaluated: 're', 'os', 'vim', 'string', 'random'.
|
|
|
|
Global variable `snip` will be available with following properties:
|
|
'snip.window' - alias for 'vim.current.window'
|
|
'snip.buffer' - alias for 'vim.current.window.buffer'
|
|
'snip.cursor' - cursor object, which behaves like
|
|
'vim.current.window.cursor', but zero-indexed and with following
|
|
additional methods:
|
|
- 'preserve()' - special method for executing pre/post/jump actions;
|
|
- 'set(line, column)' - sets cursor to specified line and column;
|
|
- 'to_vim_cursor()' - returns 1-indexed cursor, suitable for assigning
|
|
to 'vim.current.window.cursor';
|
|
'snip.line' and 'snip.column' - aliases for cursor position (zero-indexed);
|
|
'snip.visual_mode' - ('v', 'V', '^V', see |visual-mode|);
|
|
'snip.visual_text' - last visually-selected text;
|
|
'snip.last_placeholder' - last active placeholder from previous snippet
|
|
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;
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
snippet r "return" "re.match('^\s+if err ', snip.buffer[snip.line-1])" be
|
|
return err
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
That snippet will expand to 'return err' only if the previous line is starting
|
|
from 'if err' prefix.
|
|
|
|
Note: context snippets prioritized over non-context ones. It makes possible to
|
|
use non-context snippets as fallback, if no context matched:
|
|
|
|
------------------- SNIP -------------------
|
|
snippet i "if ..." b
|
|
if $1 {
|
|
$2
|
|
}
|
|
endsnippet
|
|
|
|
snippet i "if err != nil" "re.match('^\s+[^=]*err\s*:?=', snip.buffer[snip.line-1])" be
|
|
if err != nil {
|
|
$1
|
|
}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
That snippet will expand into 'if err != nil' if previous line will
|
|
match '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
|
|
used by other UltiSnips users. In that case, module should be imported
|
|
using 'global' keyword, like this:
|
|
|
|
------------------- SNIP -------------------
|
|
global !p
|
|
import my_utils
|
|
endglobal
|
|
|
|
snippet , "return ..., nil/err" "my_utils.is_return_argument(snip)" ie
|
|
, `!p if my_utils.is_in_err_condition():
|
|
snip.rv = "err"
|
|
else:
|
|
snip.rv = "nil"`
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
That snippet will expand only if the cursor is located in the return statement,
|
|
and then it will expand either to 'err' or to 'nil' depending on which 'if'
|
|
statement it's located. 'is_return_argument' and 'is_in_err_condition' are
|
|
part of custom python module which is called 'my_utils' in this example.
|
|
|
|
Context condition can return any value which python can use as condition in
|
|
it's 'if' statement, and if it's considered 'True', then snippet will be
|
|
expanded. The evaluated value of 'condition' is available in the 'snip.context'
|
|
variable inside the snippet:
|
|
|
|
------------------- SNIP -------------------
|
|
snippet + "var +=" "re.match('\s*(.*?)\s*:?=', snip.buffer[snip.line-1])" ie
|
|
`!p snip.rv = snip.context.group(1)` += $1
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
That snippet will expand to 'var1 +=' after line, which begins from 'var1 :='.
|
|
|
|
*UltiSnips-capture-placeholder*
|
|
|
|
You can capture placeholder text from previous snippet by using following
|
|
trick:
|
|
------------------- SNIP -------------------
|
|
snippet = "desc" "snip.last_placeholder" Ae
|
|
`!p snip.rv = snip.context.current_text` == nil
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
That snippet will be expanded only if you will replace selected tabstop in
|
|
other snippet (like, as in 'if ${1:var}') and will replace that tabstop by
|
|
tabstop value following by ' == nil'.
|
|
|
|
|
|
4.10 Snippets actions *UltiSnips-snippet-actions*
|
|
---------------------
|
|
|
|
Snippet actions is an arbitrary python code which can be executed at specific
|
|
points in lifetime of the snippet.
|
|
|
|
There are three types of actions:
|
|
|
|
* Pre-expand - invoked just after trigger condition was matched, but before
|
|
snippet actually expanded;
|
|
* Post-expand - invoked after snippet was expanded and interpolations
|
|
was applied for the first time, but before jump on the first placeholder.
|
|
* Jump - invoked just after jump to the next/prev placeholder.
|
|
|
|
Specified code will be evaluated at stages defined above and same global
|
|
variables and modules will be available that are stated in
|
|
the |UltiSnips-context-snippets| section.
|
|
|
|
*UltiSnips-buffer-proxy*
|
|
|
|
Note: special variable called 'snip.buffer' should be used for all buffer
|
|
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
|
|
actions.
|
|
|
|
'snip.buffer' has the same interface as 'vim.current.window.buffer'.
|
|
|
|
4.10.1 Pre-expand actions *UltiSnips-pre-expand-actions*
|
|
|
|
Pre-expand actions can be used to match snippet in one location and then
|
|
expand it in the different location. Some useful cases are: correcting
|
|
indentation for snippet; expanding snippet for function declaration in another
|
|
function body with moving expansion point beyond initial function; performing
|
|
extract method refactoring via expanding snippet in different place.
|
|
|
|
Pre-expand action declared as follows: >
|
|
pre_expand "python code here"
|
|
snippet ...
|
|
endsnippet
|
|
|
|
Buffer can be modified in pre-expand action code through variable called
|
|
'snip.buffer', snippet expansion position will be automatically adjusted.
|
|
|
|
If cursor line (where trigger was matched) need to be modified, then special
|
|
variable method 'snip.cursor.set(line, column)' must be called with the
|
|
desired cursor position. In that case UltiSnips will not remove any matched
|
|
trigger text and it should be done manually in action code.
|
|
|
|
To addition to the scope variables defined above 'snip.visual_content' will be
|
|
also declared and will contain text that was selected before snippet expansion
|
|
(similar to $VISUAL placeholder).
|
|
|
|
Following snippet will be expanded at 4 spaces indentation level no matter
|
|
where it was triggered.
|
|
|
|
------------------- SNIP -------------------
|
|
pre_expand "snip.buffer[snip.line] = ' '*4; snip.cursor.set(line, 4)"
|
|
snippet d
|
|
def $1():
|
|
$0
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
Following snippet will move the selected code to the end of file and create
|
|
new method definition for it:
|
|
|
|
------------------- SNIP -------------------
|
|
pre_expand "del snip.buffer[snip.line]; snip.buffer.append(''); snip.cursor.set(len(snip.buffer)-1, 0)"
|
|
snippet x
|
|
def $1():
|
|
${2:${VISUAL}}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
4.10.2 Post-expand actions *UltiSnips-post-expand-actions*
|
|
|
|
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
|
|
before and after method declaration), apply actions depending on python
|
|
interpolation result.
|
|
|
|
Post-expand action declared as follows: >
|
|
post_expand "python code here"
|
|
snippet ...
|
|
endsnippet
|
|
|
|
Buffer can be modified in post-expand action code through variable called
|
|
'snip.buffer', snippet expansion position will be automatically adjusted.
|
|
|
|
Variables 'snip.snippet_start' and 'snip.snippet_end' will be defined at the
|
|
action code scope and will point to positions of the start and end of expanded
|
|
snippet accordingly in the form '(line, column)'.
|
|
|
|
Note: 'snip.snippet_start' and 'snip.snippet_end' will automatically adjust to
|
|
the correct positions if post-action will insert or delete lines before
|
|
expansion.
|
|
|
|
Following snippet will expand to method definition and automatically insert
|
|
additional newline after end of the snippet. It's very useful to create a
|
|
function that will insert as many newlines as required in specific context.
|
|
|
|
------------------- SNIP -------------------
|
|
post_expand "snip.buffer[snip.snippet_end[0]+1:snip.snippet_end[0]+1] = ['']"
|
|
snippet d "Description" b
|
|
def $1():
|
|
$2
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
4.10.3 Post-jump actions *UltiSnips-post-jump-actions*
|
|
|
|
Post-jump actions can be used to trigger some code based on user input into
|
|
the placeholders. Notable use cases: expand another snippet after jump or
|
|
anonymous snippet after last jump (e.g. perform move method refactoring and
|
|
then insert new method invokation); insert heading into TOC after last jump.
|
|
|
|
Jump-expand action declared as follows: >
|
|
post_jump "python code here"
|
|
snippet ...
|
|
endsnippet
|
|
|
|
Buffer can be modified in post-jump action code through variable called
|
|
'snip.buffer', snippet expansion position will be automatically adjusted.
|
|
|
|
Next variables and methods will be also defined in the action code scope:
|
|
* 'snip.tabstop' - number of tabstop jumped onto;
|
|
* 'snip.jump_direction' - '1' if jumped forward and '-1' otherwise;
|
|
* 'snip.tabstops' - list with tabstop objects, see above;
|
|
* 'snip.snippet_start' - (line, column) of start of the expanded snippet;
|
|
* 'snip.snippet_end' - (line, column) of end of the expanded snippet;
|
|
* 'snip.expand_anon()' - alias for 'UltiSnips_Manager.expand_anon()';
|
|
|
|
Tabstop object has several useful properties:
|
|
* 'start' - (line, column) of the starting position of the tabstop (also
|
|
accessible as 'tabstop.line' and 'tabstop.col').
|
|
* 'end' - (line, column) of the ending position;
|
|
* 'current_text' - text inside the tabstop.
|
|
|
|
Following snippet will insert section in the Table of Contents in the vim-help
|
|
file:
|
|
|
|
------------------- SNIP -------------------
|
|
post_jump "if snip.tabstop == 0: insert_toc_item(snip.tabstops[1], snip.buffer)"
|
|
snippet s "section" b
|
|
`!p insert_delimiter_0(snip, t)`$1`!p insert_section_title(snip, t)`
|
|
`!p insert_delimiter_1(snip, t)`
|
|
$0
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
'insert_toc_item' will be called after first jump and will add newly entered
|
|
section into the TOC for current file.
|
|
|
|
Note: It is also possible to trigger snippet expansion from the jump action.
|
|
In that case method 'snip.cursor.preserve()' should be called, so UltiSnips
|
|
will know that cursor is already at the required position.
|
|
|
|
Following example will insert method call at the end of file after user jump
|
|
out of method declaration snippet.
|
|
|
|
------------------- SNIP -------------------
|
|
global !p
|
|
def insert_method_call(name):
|
|
vim.command('normal G')
|
|
snip.expand_anon(name + '($1)\n')
|
|
endglobal
|
|
|
|
post_jump "if snip.tabstop == 0: insert_method_call(snip.tabstops[1].current_text)"
|
|
snippet d "method declaration" b
|
|
def $1():
|
|
$2
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
4.11 Autotrigger *UltiSnips-autotrigger*
|
|
----------------
|
|
|
|
Note: vim should be newer than 7.4.214 to support this feature.
|
|
|
|
Many language constructs can occur only at specific places, so it's
|
|
possible to use snippets without manually triggering them.
|
|
|
|
Snippet can be marked as autotriggered by specifying 'A' option in the snippet
|
|
definition.
|
|
|
|
After snippet is defined as being autotriggered, snippet condition will be
|
|
checked on every typed character and if condition matches, then snippet will
|
|
be triggered.
|
|
|
|
*Warning:* using of this feature can lead to significant vim slowdown. If you
|
|
discovered that, report an issue to the github.com/SirVer/UltiSnips.
|
|
|
|
Consider following snippets, that can be usefull in Go programming:
|
|
------------------- SNIP -------------------
|
|
snippet "^p" "package" rbA
|
|
package ${1:main}
|
|
endsnippet
|
|
|
|
snippet "^m" "func main" rbA
|
|
func main() {
|
|
$1
|
|
}
|
|
endsnippet
|
|
------------------- SNAP -------------------
|
|
|
|
When "p" character will occur in the beginning of the line, it will be
|
|
automatically expanded into "package main". Same with "m" character. There is
|
|
no need to press trigger key after "m""
|
|
|
|
==============================================================================
|
|
5. UltiSnips and Other Plugins *UltiSnips-other-plugins*
|
|
|
|
5.1 Existing Integrations *UltiSnips-integrations*
|
|
-------------------------
|
|
|
|
UltiSnips has built-in support for some common plugins and there are others
|
|
that are aware of UltiSnips and use it to improve the user experience. This is
|
|
an incomplete list - if you want to have your plugin listed here, just send a
|
|
pull request.
|
|
|
|
*UltiSnips-snipMate*
|
|
|
|
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
|
|
friction now. UltiSnips is trying hard to truly emulate snipMate, for example
|
|
recursive tabstops are not supported in snipMate snippets (but of course in
|
|
UltiSnips snippets).
|
|
|
|
YouCompleteMe - comes with out of the box completion support for UltiSnips. It
|
|
offers a really nice completion dialogue for snippets.
|
|
|
|
neocomplete - UltiSnips ships with a source for neocomplete and therefore
|
|
offers out of the box completion dialogue support for it too.
|
|
|
|
unite - UltiSnips has a source for unite. As an example of how you can use
|
|
it add the following function and mappings to your vimrc: >
|
|
|
|
function! UltiSnipsCallUnite()
|
|
Unite -start-insert -winheight=100 -immediately -no-empty ultisnips
|
|
return ''
|
|
endfunction
|
|
|
|
inoremap <silent> <F12> <C-R>=(pumvisible()? "\<LT>C-E>":"")<CR><C-R>=UltiSnipsCallUnite()<CR>
|
|
nnoremap <silent> <F12> a<C-R>=(pumvisible()? "\<LT>C-E>":"")<CR><C-R>=UltiSnipsCallUnite()<CR>
|
|
|
|
When typing <F12> in either insert or normal mode you will get the unite
|
|
interface with matching snippets. Pressing enter will expand the corresponding
|
|
snippet. If only one snippet matches the text in front of the cursor will be
|
|
expanded when you press the <F12> key.
|
|
|
|
Supertab - UltiSnips has built-in support for Supertab. Just use a recent
|
|
enough version of both plugins and <tab> will either expand a snippet or defer
|
|
to Supertab for expansion.
|
|
|
|
5.2 Extending UltiSnips *UltiSnips-extending*
|
|
-------------------------
|
|
|
|
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
|
|
example can be found in `test.py`, search for AddNewSnippetSource. Please
|
|
contact us on github if you integrate UltiSnips with your plugin so it can be
|
|
listed in the docs.
|
|
|
|
=============================================================================
|
|
6. Helping Out *UltiSnips-helping*
|
|
|
|
UltiSnips needs the help of the Vim community to keep improving. Please
|
|
consider joining this effort by providing new features or bug reports.
|
|
|
|
* Clone the repository on GitHub (git clone git@github.com:SirVer/ultisnips.git),
|
|
make your changes and send a pull request on GitHub.
|
|
* Make a patch, report a bug/feature request (see below) and attach the patch
|
|
to it.
|
|
|
|
You can contribute by fixing or reporting bugs in our issue tracker:
|
|
https://github.com/sirver/ultisnips/issues
|
|
|
|
=============================================================================
|
|
7. Contributors *UltiSnips-contributors*
|
|
|
|
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
|
|
(@seletskiy).
|
|
|
|
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
|
|
git log.
|
|
|
|
JCEB - Jan Christoph Ebersbach
|
|
Michael Henry
|
|
Chris Chambers
|
|
Ryan Wooden
|
|
rupa - Rupa Deadwyler
|
|
Timo Schmiade
|
|
blueyed - Daniel Hahler
|
|
expelledboy - Anthony Jackson
|
|
allait - Alexey Bezhan
|
|
peacech - Charles Gunawan
|
|
guns - Sung Pae
|
|
shlomif - Shlomi Fish
|
|
pberndt - Phillip Berndt
|
|
thanatermesis-elive - Thanatermesis
|
|
rico-ambiescent - Rico Sta. Cruz
|
|
Cody Frazer
|
|
suy - Alejandro Exojo
|
|
grota - Giuseppe Rota
|
|
iiijjjii - Jim Karsten
|
|
fgalassi - Federico Galassi
|
|
lucapette
|
|
Psycojoker - Laurent Peuch
|
|
aschrab - Aaron Schrab
|
|
stardiviner - NagatoPain
|
|
skeept - Jorge Rodrigues
|
|
buztard
|
|
stephenmckinney - Steve McKinney
|
|
Pedro Algarvio - s0undt3ch
|
|
Eric Van Dewoestine - ervandew
|
|
Matt Patterson - fidothe
|
|
Mike Morearty - mmorearty
|
|
Stanislav Golovanov - JazzCore
|
|
David Briscoe - DavidBriscoe
|
|
Keith Welch - paralogiki
|
|
Zhao Cai - zhaocai
|
|
John Szakmeister - jszakmeister
|
|
Jonas Diemer - diemer
|
|
Romain Giot - rgiot
|
|
Sergey Alexandrov - taketwo
|
|
Brian Mock - saikobee
|
|
Gernot Höflechner - LFDM
|
|
Marcelo D Montu - mMontu
|
|
Karl Yngve Lervåg - lervag
|
|
Pedro Ferrari - petobens
|
|
Ches Martin - ches
|
|
Christian - Oberon00
|
|
Andrew Ruder - aeruder
|
|
Mathias Fußenegger - mfussenegger
|
|
Kevin Ballard - kballard
|
|
Ahbong Chang - cwahbong
|
|
Glenn Griffin - ggriffiniii
|
|
Michael - Pyrohh
|
|
Stanislav Seletskiy - seletskiy
|
|
Pawel Palucki - ppalucki
|
|
Dettorer - dettorer
|
|
Zhao Jiarong - kawing-chiu
|
|
Ye Ding - dyng
|
|
Greg Hurrell - wincent
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|