2009-07-13 04:46:14 -04:00
|
|
|
*UltiSnips.txt* The Ultimate Plugin for snippets in Vim.
|
|
|
|
|
|
|
|
UltiSnips *snippet* *snippets* *UltiSnips*
|
|
|
|
|
2010-08-20 04:04:55 -04:00
|
|
|
1. Description |UltiSnips-description|
|
|
|
|
2. Installation and Updating |UltiSnips-installnupgrade|
|
2009-07-13 06:28:58 -04:00
|
|
|
2.1 Installation |UltiSnips-installation|
|
|
|
|
2.2 Deinstallation |UltiSnips-deinstallation|
|
|
|
|
2.3 Updating |UltiSnips-updating|
|
2010-09-22 07:01:04 -04:00
|
|
|
3. Settings & Commands |UltiSnips-settings|
|
|
|
|
3.1 Commands |UltiSnips-commands|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.2 Triggers |UltiSnips-triggers|
|
|
|
|
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_AddSnippet |UltiSnips_AddSnippet|
|
|
|
|
3.5.2 UltiSnips_Anon |UltiSnips_Anon|
|
2010-08-20 04:04:55 -04:00
|
|
|
4. Syntax |UltiSnips-syntax|
|
2009-07-17 17:00:59 -04:00
|
|
|
4.1 Adding Snippets |UltiSnips-adding-snippets|
|
2011-03-31 02:01:32 -04:00
|
|
|
4.1.1 Character Escaping |UltiSnips-character-escaping|
|
2010-08-20 04:20:22 -04:00
|
|
|
4.2 Plaintext Snippets |UltiSnips-plaintext-snippets|
|
2011-02-24 17:12:51 -05:00
|
|
|
4.3 Interpolation |UltiSnips-interpolation|
|
2009-07-15 14:11:47 -04:00
|
|
|
4.3.1 Shellcode |UltiSnips-shellcode|
|
|
|
|
4.3.2 VimScript |UltiSnips-vimscript|
|
|
|
|
4.3.3 Python |UltiSnips-python|
|
2010-08-16 23:12:30 -04:00
|
|
|
4.3.4 Global Snippets |UltiSnips-globals|
|
2009-07-15 14:11:47 -04:00
|
|
|
4.4 Tab Stops and Placeholders |UltiSnips-tabstops|
|
|
|
|
4.6 Mirrors |UltiSnips-mirrors|
|
|
|
|
4.7 Transformations |UltiSnips-transformations|
|
2009-07-15 15:06:11 -04:00
|
|
|
4.7.1 Replacement String |UltiSnips-replacement-string|
|
|
|
|
4.7.2 Demos |UltiSnips-demos|
|
A "clearsnippets" feature
=========================
It's difficult for the user to control which of the default
bundled snippets are active in his environment. The
'runtimepath' variable must be set to the root of the ultisnips
installation, which brings in all of the bundled snippets.
Though the user may individually override the definition of the
bundled snippets using the "!" flag, the method has a couple of
problems:
- There's no way to remove a snippet, only to override it (and
each snippet must be overridden individually).
- The "!" flag currently doesn't remove the overridden snippets
from the "list snippets" command.
It might be considered a feature that "!" doesn't actually
remove the snippets from the "list snippets" command, though
perhaps that's an unintended effect. In any case, it would be
more convenient to allow the user to selectively remove the
bundled snippets from his environment.
A patch is provided in the following branch to address these problems:
http://code.launchpad.net/~drmikehenry/ultisnips/clearsnippets
The branch's primary purpose is the addition of a
"clearsnippets" command that may be placed in a user's
~/.vim/UltiSnips/ft.snippets file. The user may clear all
lower-priority snippet for that file type with the line:
clearsnippets
Alternatively, he may clear individual snippets by listing their
triggers:
clearsnippets trigger1 trigger2
A few changes were made to the testing system as part of the
incorporation of this new feature. These changes include:
- The "extends" directive is now supported on multiple lines
throughout file.
- A completely empty .snippets file is now possible.
- The test.py scripts now handles most of the vim setup,
simplifying the running of the tests. The invocation of Vim
now reduces to:
vim -u NONE
Instructions for running the tests are included at top of
test.py, where they should be more visible to interested
users; UltiSnips.vim now just points to test.py's
instructions.
- A new function vim_quote() encodes an arbitrary string into a
singly-quoted Vim string, with embedded quotes escaped.
- SnippetsFileParser() now allows file_data to be passed
directly for unit testing, avoiding the need to create files
in the filesystem for test purposes.
- A new _error() function reports errors to the user. At
runtime, this function uses :echo_err in general, but also can
append error text to current buffer to check for expected
errors during unit tests.
- Added error checks to snippets file parsing, along with unit
tests for the parsing.
- Increased retries from 2 to 4 (on my system, occasionally the
timing still causes tests to fail).
2009-09-08 20:15:10 -04:00
|
|
|
4.8 Clearing snippets |UltiSnips-clearing-snippets|
|
2010-08-20 04:03:09 -04:00
|
|
|
5. Helping out |UltiSnips-helping|
|
|
|
|
6. Contact |UltiSnips-contact|
|
|
|
|
7. Contributors |UltiSnips-contributors|
|
2010-08-20 04:30:33 -04:00
|
|
|
7.1 Patches & Coding |UltiSnips-contricoding|
|
|
|
|
7.2 Snippets |UltiSnips-contrisnippets|
|
2009-07-13 04:46:14 -04:00
|
|
|
|
|
|
|
For Vim version 7.0 or later.
|
|
|
|
This plugin only works if 'compatible' is not set.
|
|
|
|
{Vi does not have any of these features}
|
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
This plugin needs Python support >= 2.6 compiled into Vim.
|
2009-07-13 04:46:14 -04:00
|
|
|
|
|
|
|
=============================================================================
|
|
|
|
DESCRIPTION *UltiSnips-description*
|
|
|
|
|
|
|
|
UltiSnips aims to provide a snippets solution that users came to expect from
|
|
|
|
editors. A Snippet is a short piece of text which is either typed very often
|
|
|
|
or which contains a lot of redundant text. Such snippets are very often
|
|
|
|
encountered in structured text like Source Code but I also use them for email
|
|
|
|
signatures and to insert the current date or time into the text while typing.
|
|
|
|
|
|
|
|
UltiSnips is an implementation that is developed with in the philosophy of TDD
|
|
|
|
(Test driven development). This guarantees that features do not disappear and
|
2010-08-20 04:04:55 -04:00
|
|
|
bugs do not reappear after they have been fixed once.
|
2009-07-13 04:46:14 -04:00
|
|
|
|
2009-07-15 15:06:11 -04:00
|
|
|
Acknowledgments: *UltiSnips-acknowledgments*
|
|
|
|
|
|
|
|
UltiSnips is inspired by the snippets solution implemented in TextMate
|
|
|
|
(http://macromates.com/). The idea of implementing snippets for vim is not new
|
|
|
|
and I want to thank Michael Sander (Author of snipMate) for some
|
|
|
|
implementation details I stole from him and for the permission to use some of
|
|
|
|
his snippets.
|
|
|
|
|
2009-07-13 04:46:14 -04:00
|
|
|
=============================================================================
|
2009-07-13 06:28:58 -04:00
|
|
|
2. INSTALLATION AND UPDATING *UltiSnips-installnupdate*
|
|
|
|
|
|
|
|
|
|
|
|
2.1 Installation *UltiSnips-installation*
|
|
|
|
----------------
|
2009-07-13 04:46:14 -04:00
|
|
|
|
|
|
|
UltiSnips has only been tested on Mac OS X and Linux. Like TextMates Snippets
|
|
|
|
it also relies heavily on shell integration, therefore Windows users will have
|
2010-08-20 04:04:55 -04:00
|
|
|
only a part of the functionality.
|
2009-07-13 04:46:14 -04:00
|
|
|
|
2010-08-20 04:04:55 -04:00
|
|
|
To use UltiSnips, you need a python enabled Vim 7. You have python if
|
2009-07-13 04:46:14 -04:00
|
|
|
:echo has("python")
|
|
|
|
yields '1'.
|
|
|
|
|
|
|
|
If you have Python, you only need to install UltiSnips. The recommended way to
|
|
|
|
do so is by using bzr (http://bazaar-vcs.org/). It is in all major linux
|
|
|
|
distribution (either package bzr or bazaar) and can be easily installed under
|
2009-07-13 06:28:58 -04:00
|
|
|
Mac OS X: >
|
2009-07-13 04:46:14 -04:00
|
|
|
$ easy_install bzr
|
|
|
|
|
|
|
|
To get UltiSnips, check it out into a directory of your choice. Then add this
|
2009-07-13 06:28:58 -04:00
|
|
|
directory to your Vim runtime path: >
|
2009-07-13 04:46:14 -04:00
|
|
|
$ cd ~/.vim/
|
|
|
|
$ bzr get lp:ultisnips ultisnips_rep
|
|
|
|
$ vim ~/.vimrc
|
2009-07-13 06:28:58 -04:00
|
|
|
|
|
|
|
add the line: >
|
2009-07-13 04:46:14 -04:00
|
|
|
set runtimepath+=~/.vim/ultisnips_rep
|
|
|
|
|
2009-07-15 10:28:33 -04:00
|
|
|
Restart vim. UltiSnips should work now. To access the help, use >
|
|
|
|
:helptags ~/.vim/ultisnips_rep/doc
|
|
|
|
:help UltiSnips
|
2009-07-13 04:46:14 -04:00
|
|
|
|
2009-07-13 06:28:58 -04:00
|
|
|
2.2 Deinstallation *UltiSnips-deinstallation*
|
|
|
|
------------------
|
2009-07-13 04:46:14 -04:00
|
|
|
|
|
|
|
To Uninstall UltiSnips, remove the directory you installed it to and remove
|
2009-07-13 06:28:58 -04:00
|
|
|
the path from your vim runtimepath: >
|
2009-07-13 04:46:14 -04:00
|
|
|
$ rm -rf ~/.vim/ultisnips_rep
|
|
|
|
$ vim ~/.vimrc
|
2009-07-13 06:28:58 -04:00
|
|
|
|
|
|
|
remove the line: >
|
2009-07-13 04:46:14 -04:00
|
|
|
set runtimepath+=~/.vim/ultisnips_rep
|
|
|
|
|
2009-07-13 06:28:58 -04:00
|
|
|
2.3 Updating *UltiSnips-updating*
|
|
|
|
------------
|
|
|
|
|
|
|
|
To Update an installation, simply pull the latest revision: >
|
|
|
|
$ cd ~/.vim/ultisnips_rep
|
2010-08-20 04:04:55 -04:00
|
|
|
$ bzr pull
|
2009-07-13 06:28:58 -04:00
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
=============================================================================
|
|
|
|
3. SETTINGS *UltiSnips-settings*
|
|
|
|
|
2010-09-22 07:01:04 -04:00
|
|
|
3.1 Commands *UltiSnips-commands*
|
|
|
|
------------
|
|
|
|
|
|
|
|
UltiSnips defines two Commands, the first one is UltiSnipsReset, which will
|
|
|
|
reload the snippets definitions and is useful while you are tweaking a
|
|
|
|
snippet.
|
|
|
|
UltiSnipsEdit is the second one. It opens your private snippet definition file
|
|
|
|
for the current filetype. You can easily open them manually of course, this is
|
|
|
|
just a shortcut. There is also a variable called: >
|
|
|
|
|
2011-03-07 11:53:11 -05:00
|
|
|
g:UltiSnipsEditSplit
|
2010-09-22 07:01:04 -04:00
|
|
|
|
2011-03-07 11:53:11 -05:00
|
|
|
which can be set to "normal" (default), "horizontal" or "vertical" that
|
|
|
|
defines if a new window should be opened for the edit.
|
2010-09-22 07:01:04 -04:00
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.2 Triggers *UltiSnips-triggers*
|
|
|
|
------------
|
2010-09-22 07:01:04 -04:00
|
|
|
|
2009-07-21 04:21:05 -04:00
|
|
|
You can freely define the keys used to expand a snippet and jump forward and
|
2009-08-16 14:55:08 -04:00
|
|
|
backwards in it. There is also a key to list all snippets available for the
|
|
|
|
current expand situation. The variables with the default values are: >
|
2009-07-21 04:21:05 -04:00
|
|
|
g:UltiSnipsExpandTrigger <tab>
|
2009-08-16 14:55:08 -04:00
|
|
|
g:UltiSnipsListSnippets <c-tab>
|
2009-07-21 04:21:05 -04:00
|
|
|
g:UltiSnipsJumpForwardTrigger <c-j>
|
|
|
|
g:UltiSnipsJumpBackwardTrigger <c-k>
|
|
|
|
|
|
|
|
It is possible to set the Expand and Forward trigger to the same value. You
|
|
|
|
can get a more TextMate like configuration by adding the next three lines to
|
|
|
|
you vimrc: >
|
2010-08-20 04:04:55 -04:00
|
|
|
let g:UltiSnipsExpandTrigger="<tab>"
|
|
|
|
let g:UltiSnipsJumpForwardTrigger="<tab>"
|
|
|
|
let g:UltiSnipsJumpBackwardTrigger="<s-tab>"
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.3 Snippet Search Path *UltiSnips-snippet-search-path*
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
UltiSnips lets you override the name of the directories that are searched
|
|
|
|
for snippets. You need to set the variable g:UltiSnipsSnippetDirectories,
|
|
|
|
which defaults to: >
|
|
|
|
g:UltiSnipsSnippetDirectories ["UltiSnips"]
|
|
|
|
|
|
|
|
Snippet definition files are searched in 'runtimepath', but the 'runtimepath'
|
|
|
|
variable is traversed in reversed order (last item first). In each directory,
|
|
|
|
UltiSnips will search for the folder names in the order they appear in
|
|
|
|
g:UltiSnipsSnippetDirectories. If you keep your snippets in a folder called
|
|
|
|
"mycoolsnippets" in your .vim directory and you want the snippets that ship
|
|
|
|
with UltiSnips to be available as well, use >
|
|
|
|
let g:UltiSnipsSnippetDirectories=["UltiSnips", "mycoolsnippets"]
|
|
|
|
If you do not want the shipped snippets to be available, only use
|
|
|
|
"mycoolsnippets".
|
2010-09-22 07:01:04 -04:00
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
See |UltiSnips-adding-snippet| for an introduction which files are parsed for
|
|
|
|
which file type.
|
|
|
|
|
|
|
|
3.4 Warning About Select Mode Mappings *UltiSnips-warning-smappings*
|
2010-08-20 04:20:22 -04:00
|
|
|
--------------------------------------
|
|
|
|
|
|
|
|
The help for vim's *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.
|
|
|
|
|
|
|
|
But most vim plugins (even the ones shipped with vim) do not adhere to this.
|
|
|
|
As UltiSnips uses select mode to mark tabstops in snippets for overwriting
|
|
|
|
these wrong mappings get in the way. UltiSnips therefore defaults to
|
|
|
|
*:sunmap* all mappings for printable characters in select mode. It will not
|
|
|
|
touch any other mappings, especially not normal, insert or visual mode
|
|
|
|
mappings.
|
|
|
|
|
|
|
|
If this behaviour is not desired, you can disable it via >
|
|
|
|
let g:UltiSnipsRemoveSelectModeMappings = 0
|
|
|
|
|
|
|
|
If you want to keep certain mappings, you can modify the list of ignores for
|
|
|
|
this feature. For example >
|
|
|
|
let g:UltiSnipsMappingsToIgnore = [ "somePlugin", "otherPlugin" ]
|
|
|
|
|
|
|
|
will not unmap any mapping that contains the string "somePlugin" or
|
|
|
|
"otherPlugin" in its complete definition as listed by *:smap* .
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2010-12-20 21:49:55 -05:00
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.5 Functions *UltiSnips-functions*
|
2010-12-20 21:49:55 -05:00
|
|
|
-------------
|
|
|
|
|
2011-04-09 11:48:14 -04:00
|
|
|
UltiSnips provides two functions for extending core functionality.
|
2010-12-20 21:49:55 -05:00
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.5.1 UltiSnips_AddSnippet *UltiSnips_AddSnippet*
|
2010-12-20 21:49:55 -05:00
|
|
|
|
|
|
|
The first function is UltiSnips_AddSnippet(trigger, value, description,
|
|
|
|
options, ...) which adds a new snippet to the current list of snippets with
|
|
|
|
the provided trigger, value, description, and options, see |UltiSnips-syntax|
|
|
|
|
for details on the meaning of those. All of the arguments are strings. You can
|
|
|
|
also specify the filetype for the new snippet with the final optional
|
|
|
|
argument.
|
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
3.5.2 UltiSnips_Anon *UltiSnips_Anon*
|
2010-12-20 21:49:55 -05:00
|
|
|
|
|
|
|
The second function is UltiSnips_Anon(value, ...), which expands an anonymous
|
|
|
|
Snippet. The snippet that gets expanded doesn't get added to the global list
|
|
|
|
of snippets, so it can't be expanded a second time unless the function is
|
|
|
|
called again. The value argument is the same as |UltiSnips_AddSnippet|. There
|
|
|
|
are also optional arguments, which are 1) the trigger, 2) the description of
|
|
|
|
the snippet, and 3) the options. All of the optional arguments are the same as
|
|
|
|
the |UltiSnips_AddSnippet| function. The description is unused right now,
|
|
|
|
whereas the trigger and options can change the way the snippet expands.
|
|
|
|
|
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
=============================================================================
|
|
|
|
4. SYNTAX *UltiSnips-syntax*
|
|
|
|
|
|
|
|
This chapter describes where to add new snippets and how to write them. I'll
|
2010-08-20 04:04:55 -04:00
|
|
|
provide many examples to make things clearer.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
4.1 Adding Snippets *UltiSnips-adding-snippets*
|
|
|
|
-------------------
|
|
|
|
|
2011-03-31 01:40:56 -04:00
|
|
|
See |UltiSnips-snippet-search-path| for an explanation of where directories
|
|
|
|
with snippet definitions are expected.
|
|
|
|
|
|
|
|
While iterating over the snippet definition directories found, files are
|
2009-07-15 14:11:47 -04:00
|
|
|
looked for called ft.snippets, for example: >
|
|
|
|
ruby.snippets
|
|
|
|
c.snippets
|
|
|
|
perl.snippets
|
|
|
|
These files contain the snippet definitions for the various file types. A
|
|
|
|
special file is >
|
|
|
|
all.snippets
|
|
|
|
which contains snippets that are always expanded, no matter what file type is
|
2010-08-20 04:04:55 -04:00
|
|
|
defined. For example, I keep mail signatures and date insertion snippets here.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2009-07-17 17:00:59 -04:00
|
|
|
The dotted file type syntax of vim is supported. For example, for my cpp or
|
|
|
|
CUDA files, i keep the file type set to ":set ft=cpp.c" or ":set
|
|
|
|
ft=cuda.cpp.c". This activates all snippets for each file type in the order
|
|
|
|
specified.
|
|
|
|
|
A "clearsnippets" feature
=========================
It's difficult for the user to control which of the default
bundled snippets are active in his environment. The
'runtimepath' variable must be set to the root of the ultisnips
installation, which brings in all of the bundled snippets.
Though the user may individually override the definition of the
bundled snippets using the "!" flag, the method has a couple of
problems:
- There's no way to remove a snippet, only to override it (and
each snippet must be overridden individually).
- The "!" flag currently doesn't remove the overridden snippets
from the "list snippets" command.
It might be considered a feature that "!" doesn't actually
remove the snippets from the "list snippets" command, though
perhaps that's an unintended effect. In any case, it would be
more convenient to allow the user to selectively remove the
bundled snippets from his environment.
A patch is provided in the following branch to address these problems:
http://code.launchpad.net/~drmikehenry/ultisnips/clearsnippets
The branch's primary purpose is the addition of a
"clearsnippets" command that may be placed in a user's
~/.vim/UltiSnips/ft.snippets file. The user may clear all
lower-priority snippet for that file type with the line:
clearsnippets
Alternatively, he may clear individual snippets by listing their
triggers:
clearsnippets trigger1 trigger2
A few changes were made to the testing system as part of the
incorporation of this new feature. These changes include:
- The "extends" directive is now supported on multiple lines
throughout file.
- A completely empty .snippets file is now possible.
- The test.py scripts now handles most of the vim setup,
simplifying the running of the tests. The invocation of Vim
now reduces to:
vim -u NONE
Instructions for running the tests are included at top of
test.py, where they should be more visible to interested
users; UltiSnips.vim now just points to test.py's
instructions.
- A new function vim_quote() encodes an arbitrary string into a
singly-quoted Vim string, with embedded quotes escaped.
- SnippetsFileParser() now allows file_data to be passed
directly for unit testing, avoiding the need to create files
in the filesystem for test purposes.
- A new _error() function reports errors to the user. At
runtime, this function uses :echo_err in general, but also can
append error text to current buffer to check for expected
errors during unit tests.
- Added error checks to snippets file parsing, along with unit
tests for the parsing.
- Increased retries from 2 to 4 (on my system, occasionally the
timing still causes tests to fail).
2009-09-08 20:15:10 -04:00
|
|
|
As an alternative, a snippet file may contain a line that looks like this: >
|
2009-08-02 05:57:43 -04:00
|
|
|
extends ft1, ft2, ft3
|
|
|
|
For example, the first line in cpp.snippets looks like this: >
|
|
|
|
extends c
|
|
|
|
This means, first check all triggers for c, then add the triggers from this
|
|
|
|
file. This is a convenient way to add more special cases to more general ones.
|
A "clearsnippets" feature
=========================
It's difficult for the user to control which of the default
bundled snippets are active in his environment. The
'runtimepath' variable must be set to the root of the ultisnips
installation, which brings in all of the bundled snippets.
Though the user may individually override the definition of the
bundled snippets using the "!" flag, the method has a couple of
problems:
- There's no way to remove a snippet, only to override it (and
each snippet must be overridden individually).
- The "!" flag currently doesn't remove the overridden snippets
from the "list snippets" command.
It might be considered a feature that "!" doesn't actually
remove the snippets from the "list snippets" command, though
perhaps that's an unintended effect. In any case, it would be
more convenient to allow the user to selectively remove the
bundled snippets from his environment.
A patch is provided in the following branch to address these problems:
http://code.launchpad.net/~drmikehenry/ultisnips/clearsnippets
The branch's primary purpose is the addition of a
"clearsnippets" command that may be placed in a user's
~/.vim/UltiSnips/ft.snippets file. The user may clear all
lower-priority snippet for that file type with the line:
clearsnippets
Alternatively, he may clear individual snippets by listing their
triggers:
clearsnippets trigger1 trigger2
A few changes were made to the testing system as part of the
incorporation of this new feature. These changes include:
- The "extends" directive is now supported on multiple lines
throughout file.
- A completely empty .snippets file is now possible.
- The test.py scripts now handles most of the vim setup,
simplifying the running of the tests. The invocation of Vim
now reduces to:
vim -u NONE
Instructions for running the tests are included at top of
test.py, where they should be more visible to interested
users; UltiSnips.vim now just points to test.py's
instructions.
- A new function vim_quote() encodes an arbitrary string into a
singly-quoted Vim string, with embedded quotes escaped.
- SnippetsFileParser() now allows file_data to be passed
directly for unit testing, avoiding the need to create files
in the filesystem for test purposes.
- A new _error() function reports errors to the user. At
runtime, this function uses :echo_err in general, but also can
append error text to current buffer to check for expected
errors during unit tests.
- Added error checks to snippets file parsing, along with unit
tests for the parsing.
- Increased retries from 2 to 4 (on my system, occasionally the
timing still causes tests to fail).
2009-09-08 20:15:10 -04:00
|
|
|
Multiple "extends" lines are permitted throughout the snippets file.
|
2009-08-02 05:57:43 -04:00
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
The snippets file format is simple. A line starting with # is a comment, each
|
|
|
|
snippet starts with a line in the form of: >
|
2009-07-17 17:33:48 -04:00
|
|
|
snippet tab_trigger [ "description" [ options ] ]
|
2009-07-15 14:11:47 -04:00
|
|
|
The following lines are the snippets definition; a line starting with >
|
|
|
|
endsnippet
|
|
|
|
marks the end of the snippet. The trailing newline is chopped from the
|
2009-07-17 17:33:48 -04:00
|
|
|
definition. In the starting line, the description and options are optional.
|
|
|
|
|
2010-08-08 21:15:34 -04:00
|
|
|
If you want to use a multi-word trigger, you can surround the trigger with any
|
2011-03-07 11:53:11 -05:00
|
|
|
single character on each side. e.g. >
|
2010-08-08 21:15:34 -04:00
|
|
|
snippet "tab trigger" [ "description" [ options ] ]
|
|
|
|
or >
|
|
|
|
snippet !"tab trigger"! [ "description" [ options ] ]
|
|
|
|
if you actually want to include the double-quote characters in the trigger.
|
|
|
|
|
2009-07-17 17:33:48 -04:00
|
|
|
The description is only needed when more than one snippet is defined with the
|
|
|
|
same tab trigger. The user is then given a choice and the description is
|
2010-08-20 04:04:55 -04:00
|
|
|
displayed for the user as helper.
|
2009-07-17 17:33:48 -04:00
|
|
|
|
|
|
|
The options is a word of characters, each turning a specific option for this
|
|
|
|
snippet on. The options currently supported are >
|
|
|
|
! Overwrite - This snippet will overwrite all previously defined
|
|
|
|
snippets with this tab trigger. Default is to let the user choose at
|
|
|
|
expansion which snippet to expand. This option is useful to overwrite
|
|
|
|
bundled tab stops with user defined ones.
|
2009-07-17 18:51:19 -04:00
|
|
|
b Beginning of line - This snippet will only be expanded if you are at
|
|
|
|
the beginning of a line (that is if there are only whitespaces in front
|
|
|
|
of the cursor). Default is to expand snippets at every position, even
|
2011-03-07 11:53:11 -05:00
|
|
|
in the middle of a line. Most of my snippets have this option set, it
|
|
|
|
keeps UltiSnips out of the way.
|
2009-08-23 18:44:19 -04:00
|
|
|
i Inword expansion - Normally, triggers need whitespace before them to be
|
2009-08-16 10:34:54 -04:00
|
|
|
expanded. With this option, triggers are also expanded in the middle of
|
|
|
|
a word.
|
2009-08-23 18:44:19 -04:00
|
|
|
w Word boundary - Normally, triggers need whitespace before them to be
|
|
|
|
expanded. With this option, the trigger will be expanded at a "word"
|
|
|
|
boundary as well, where word characters are letters, digits, and the
|
|
|
|
underscore character ('_'). This enables expansion of a trigger that
|
|
|
|
adjoins punctuation (for example) without expanding suffixes of larger
|
|
|
|
words.
|
2010-08-08 21:15:34 -04:00
|
|
|
r Regular expression - This uses a python regular expression for the
|
|
|
|
match. The regular expression MUST be surrounded like a multi-word
|
|
|
|
trigger (see above) even if it doesn't have any spaces. The resulting
|
|
|
|
match is also passed to any python code blocks in your snippet
|
2010-08-16 23:12:30 -04:00
|
|
|
definition as the local variable "match".
|
2010-11-22 09:14:47 -05:00
|
|
|
t Don't expand tabs - By default, UltiSnips tries to expand leading tabs
|
|
|
|
in a snippet to match the results of automatic indentation. If this
|
|
|
|
option is set, UltiSnips will not try to do this expansion, and will
|
|
|
|
leave the tabs alone. This can be useful for snippets dealing with
|
2011-03-31 02:01:32 -04:00
|
|
|
tab delimited formats, etc.
|
2011-04-09 11:48:14 -04:00
|
|
|
f Do not turn 'formatoptions' off when expanding the snippet. Normally,
|
|
|
|
UltiSnips will disable the 'c' and the 't' option of 'formatoptions'
|
|
|
|
because otherwise, Vim might break a line without UltiSnips noticing
|
|
|
|
and this might mess up the snippet completely. This is useful for
|
|
|
|
snippets that need paragraphs in their tabstops.
|
2011-03-31 02:01:32 -04:00
|
|
|
<
|
|
|
|
|
|
|
|
4.1.1 Character Escaping: *UltiSnips-character-escaping*
|
|
|
|
|
|
|
|
In the snippet descriptions, various characters have special meaning
|
|
|
|
(e.g. '`{$\). If you want to insert any one of these characters literally,
|
|
|
|
prepend them with a single backslash (\).
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2010-08-20 04:20:22 -04:00
|
|
|
4.2 Plaintext Snippets *UltiSnips-plaintext-snippets*
|
2009-07-15 14:11:47 -04:00
|
|
|
----------------------
|
|
|
|
|
|
|
|
Lets start with a simple example. Add this to your all snippets file: >
|
|
|
|
~/.vim/UltiSnips/all.snippets
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet bye "My mail signature"
|
|
|
|
Good bye, Sir. Hope to talk to you soon.
|
|
|
|
- Arthur, King of Britain
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
|
|
|
|
Now, restart vim or reset UltiSnips by typing >
|
2011-03-31 02:01:32 -04:00
|
|
|
:UltiSnipsReset
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
now try it in insert mode:
|
|
|
|
bye<tab> -->
|
|
|
|
Good bye, Sir. Hope to talk to you soon.
|
|
|
|
- Arthur, King of Britain
|
|
|
|
|
|
|
|
4.3 Interpolation *UltiSnips-interpolation*
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
4.3.1 Shellcode: *UltiSnips-shellcode*
|
|
|
|
|
|
|
|
You can enter shellcode in your snippets in nearly all places. Shell code is
|
|
|
|
written to a script and then executed. The output is inserted into the snippet
|
|
|
|
instead of the shell code itself. Since the code is executed as a shell
|
|
|
|
script, you can use #!/bin/ notation to feed the input of your code to every
|
|
|
|
program you like. Let's consider an example that inserts the current date.
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet today
|
|
|
|
Today is the `date +%d.%m.%y`.
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
|
|
|
|
today<tab> ->
|
|
|
|
Today is the 15.07.09.
|
|
|
|
|
|
|
|
Another example doing the same 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.3.2 VimScript: *UltiSnips-vimscript*
|
|
|
|
|
|
|
|
You can also use VimScript (also sometimes called VimL) in interpolation. This
|
|
|
|
works very much the same as interpolation of shellcode, expect that it must be
|
|
|
|
started by using `!v `. Let's consider a simple 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.3.3 Python: *UltiSnips-python*
|
|
|
|
|
|
|
|
By far the most powerful interpolation is by using python code. The syntax is
|
2010-07-29 22:02:15 -04:00
|
|
|
similar to the one for Vimscript, but in python code the value of the property
|
|
|
|
"rv" on the "snip" object is inserted at the position of the code. Also, the
|
|
|
|
code is inside a `!p ` block. Python code gets some special variables defined
|
|
|
|
which can be used: >
|
2010-08-20 04:04:55 -04:00
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
fn - The current filename
|
|
|
|
path - The complete path to the current file
|
|
|
|
t - The values of the placeholders, t[1] -> current text of ${1} and so on
|
2010-08-16 23:12:30 -04:00
|
|
|
snip - Provides easy indentation handling.
|
2010-05-16 18:34:44 -04:00
|
|
|
|
2010-07-30 20:21:05 -04:00
|
|
|
The snip object provides the following methods: >
|
2010-05-16 18:34:44 -04:00
|
|
|
|
|
|
|
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.
|
2010-08-20 04:04:55 -04:00
|
|
|
|
2010-05-16 18:34:44 -04:00
|
|
|
snip.shift(amount=1):
|
2010-07-29 22:02:15 -04:00
|
|
|
Shifts the default indentation level used by mkline right by the
|
2010-05-16 18:34:44 -04:00
|
|
|
number of spaces defined by shiftwidth, 'amount' times.
|
|
|
|
|
|
|
|
snip.unshift(amount=1):
|
2010-07-29 22:02:15 -04:00
|
|
|
Shifts the default indentation level used by mkline left by the
|
2010-05-16 18:34:44 -04:00
|
|
|
number of spaces defined by shiftwidth, 'amount' times.
|
|
|
|
|
|
|
|
snip.reset_indent():
|
|
|
|
Resets the indentation level to its initial value.
|
2010-08-20 04:04:55 -04:00
|
|
|
|
2010-07-29 22:02:15 -04:00
|
|
|
snip.opt(var, default):
|
|
|
|
Checks if the vim variable "var" has been set, if so, it returns it,
|
|
|
|
otherwise it returns "default".
|
|
|
|
|
2010-07-30 20:21:05 -04:00
|
|
|
The snip object provides some properties as well: >
|
|
|
|
|
2010-07-30 20:54:51 -04:00
|
|
|
snip.rv:
|
|
|
|
the text that will fill this python block's position, it always starts
|
|
|
|
out as an empty string. This deprecates the "res" variable.
|
|
|
|
|
|
|
|
snip.c:
|
|
|
|
the text currently in the python block's position in the snippet
|
|
|
|
in it. You can check if snip.c is != "" to make sure that the
|
|
|
|
interpolation is only done once. This deprecates the "cur" variable.
|
2010-07-29 22:02:15 -04:00
|
|
|
|
2010-07-30 20:21:05 -04:00
|
|
|
snip.fn:
|
|
|
|
the current filename.
|
|
|
|
|
|
|
|
snip.basename:
|
|
|
|
the current filename without it's extension.
|
|
|
|
|
|
|
|
snip.ft:
|
|
|
|
the current filetype.
|
|
|
|
|
|
|
|
The snip object also provides some operators to make python snippets
|
2010-07-29 22:02:15 -04:00
|
|
|
easier: >
|
2010-05-16 18:34:44 -04:00
|
|
|
|
2010-07-29 22:02:15 -04:00
|
|
|
snip >> amount:
|
|
|
|
is equivalent to snip.shift(amount)
|
|
|
|
snip << amount:
|
|
|
|
is equivalent to snip.unshift(amount)
|
|
|
|
snip += line:
|
|
|
|
is equivalent to "snip.rv += '\n' + snip.mkline(line)"
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2010-08-16 23:12:30 -04:00
|
|
|
Any variables set in a python block can be used in any following blocks.
|
2009-07-19 10:44:29 -04:00
|
|
|
Also, the vim, re, os, string and random modules are already imported inside
|
|
|
|
the snippet code. This allows for very flexible snippets. For example, the
|
|
|
|
following snippet mirrors the first Tab Stops value on the same line in
|
|
|
|
uppercase and right aligned:
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet wow
|
2010-08-20 04:04:55 -04:00
|
|
|
${1:Text}`!p snip.rv = (75-2*len(t[1]))*' '+t[1].upper()`
|
2009-07-15 14:11:47 -04:00
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
wow<tab>Hello World ->
|
2010-08-20 04:04:55 -04:00
|
|
|
Hello World HELLO WORLD
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2010-08-16 23:12:30 -04:00
|
|
|
4.3.4 Global Snippets: *UltiSnips-globals*
|
|
|
|
|
|
|
|
Global snippets provide a way to take common code out of snippets. Currently,
|
|
|
|
only python code is supported. The result of executing the contents of the
|
|
|
|
snippet is put into the globals of each python block in the snippet file. To
|
|
|
|
create a global snippet, you use the keyword "global" in place of "snippet",
|
|
|
|
and for python code, you use "!p" for the trigger, for example, the following
|
|
|
|
is identical to the previous example, except that "upper_right" can be reused:
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
global !p
|
|
|
|
def upper_right(inp):
|
|
|
|
return (75 - 2 * len(inp))*' ' + inp.upper()
|
|
|
|
endglobal
|
|
|
|
|
|
|
|
snippet wow
|
2010-08-20 04:04:55 -04:00
|
|
|
${1:Text}`!p snip.rv = upper_right(t[1])`
|
2010-08-16 23:12:30 -04:00
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
wow<tab>Hello World ->
|
2010-08-20 04:04:55 -04:00
|
|
|
Hello World HELLO WORLD
|
2010-08-16 23:12:30 -04:00
|
|
|
|
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
4.4 Tab Stops and Placeholders *UltiSnips-tabstops* *UltiSnips-placeholders*
|
|
|
|
------------------------------
|
|
|
|
|
|
|
|
Very often, it is convenient to quickly add some text snippet and jump on to
|
|
|
|
the next point of interest. This is were tabstops come in:
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet jump
|
|
|
|
I $1 I was a $2.
|
|
|
|
$0
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
jump<tab>wish<c-j>hunter<c-j>more text ->
|
|
|
|
I wish I was a hunter.
|
|
|
|
more text
|
|
|
|
|
|
|
|
You can use <c-j> and <c-k> to jump to the next tab or the previous. <Tab> was
|
|
|
|
not used for jumping forward because many people (like myself) use <tab> also
|
|
|
|
for completion. $0 is a special tab: This is the last tab in the snippet, no
|
2010-08-20 04:04:55 -04:00
|
|
|
matter how many tabs were defined before.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
Most of the time it is more useful to have some default text for a tabstop and
|
|
|
|
sometimes it is also useful to have a tab stop in a tab stop. Consider the
|
|
|
|
next example which could be a real life scenario from a HTML snippet:
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet a
|
|
|
|
<a href="$1"${2: class="${3:link}"}>
|
|
|
|
$0
|
|
|
|
</a>
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
|
|
|
|
Here, $1 marks the first tabstop; it is assumed that you always want to add a
|
|
|
|
url as href. After entering it you jump to $2 which has the default text '
|
|
|
|
class="link"'. Now, you can either hit backspace, because you do not want to
|
|
|
|
enter a class attribute for this tag or you hit <c-j> to change the class name
|
|
|
|
(which is tab stop $3). When you are satisfied with the first line you hit
|
2011-03-07 11:53:11 -05:00
|
|
|
<c-j> again to finish this snippet and continue inside the anchor.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
a<tab>http://www.google.com<c-j><BS><c-j>hi ->
|
|
|
|
<a href="http://www.google.com">
|
|
|
|
hi
|
|
|
|
</a>
|
|
|
|
|
|
|
|
a<tab>http://www.google.com<c-j><c-j>visited<c-j>hi ->
|
|
|
|
<a href="http://www.google.com" class="visited">
|
|
|
|
hi
|
|
|
|
</a>
|
|
|
|
|
|
|
|
Default tab stop text can also contain mirrors, transformations or
|
2010-08-20 04:04:55 -04:00
|
|
|
interpolation.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
4.6 Mirrors *UltiSnips-mirrors*
|
|
|
|
-----------
|
|
|
|
|
2009-07-15 15:06:11 -04:00
|
|
|
Mirrors simply repeat the content of a tabstop. A classical example would be a
|
|
|
|
TeX Environment which needs a \begin{} and an \end{} tag:
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet env
|
|
|
|
\begin{${1:enumerate}}
|
|
|
|
$0
|
|
|
|
\end{$1}
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
env<tab>itemize ->
|
|
|
|
\begin{itemize}
|
2010-08-20 04:04:55 -04:00
|
|
|
|
2009-07-15 15:06:11 -04:00
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
Another typical example is #ifndef block in C code:
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet ifndef
|
|
|
|
#ifndef ${1:SOME_DEFINE}
|
|
|
|
#define $1
|
|
|
|
$0
|
|
|
|
#endif /* $1 */
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
ifndef<tab>WIN32 ->
|
|
|
|
#ifndef WIN32
|
|
|
|
#define WIN32
|
|
|
|
|
|
|
|
#endif /* WIN32 */
|
2009-07-15 14:11:47 -04:00
|
|
|
|
|
|
|
4.7 Transformations *UltiSnips-transformations*
|
|
|
|
-------------------
|
|
|
|
|
2009-07-15 15:06:11 -04:00
|
|
|
A complete description of the features follows, the chapter closes with some
|
2010-08-20 04:04:55 -04:00
|
|
|
demos, because this feature is rather mighty and hard to understand.
|
2009-07-15 15:06:11 -04:00
|
|
|
|
|
|
|
Transformations are like mirrors. But instead of just verbatim copying text
|
|
|
|
from the original tab stop, a regular expression is matched to the content of
|
|
|
|
the referenced tab stop and a transformation is then applied to the matched
|
|
|
|
pattern. UltiSnips follows the syntax and features of TextMate very closely
|
2010-08-20 04:04:55 -04:00
|
|
|
here.
|
2009-07-15 15:06:11 -04:00
|
|
|
|
|
|
|
A Transformation has the syntax >
|
|
|
|
${<tab stop no/regular expression/replacement/options}
|
|
|
|
|
|
|
|
with >
|
|
|
|
tab stop no - The number of the tab stop to reference
|
|
|
|
regular expression - The regular expression to match to the value of the
|
|
|
|
tab stop
|
|
|
|
replacement - The replacement string, see below
|
|
|
|
options - options for the regular expression
|
|
|
|
|
|
|
|
The options can be any combination of >
|
|
|
|
g - global replace, replaces all matches of the regular expression, not
|
|
|
|
just the first
|
|
|
|
|
|
|
|
Regular expressions are not handled here. Python regular expressions are used
|
2010-08-20 04:04:55 -04:00
|
|
|
internally, so the reference for matching is the re module of python:
|
2009-07-15 15:06:11 -04:00
|
|
|
http://docs.python.org/library/re.html
|
|
|
|
|
|
|
|
The replacement string is using a own syntax and is handled in the next paragraph.
|
|
|
|
|
|
|
|
4.7.1 Replacement String: *UltiSnips-replacement-string*
|
|
|
|
|
|
|
|
The replacement string can contain $no variables to reference matched groups
|
|
|
|
in the regular expression, $0 is special and yields the whole match. The
|
|
|
|
replacement string can also contain special escape sequences: >
|
2010-08-20 04:04:55 -04:00
|
|
|
\u - Uppercase next letter;
|
2009-07-15 15:06:11 -04:00
|
|
|
\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
|
|
|
|
|
|
|
|
Last, but not least the replacement string might contain conditional
|
|
|
|
replacements with the following syntax (?no:text:other text). This reads as
|
|
|
|
follows: if the group $no has matched, insert "text", otherwise insert "other
|
|
|
|
text". "other text" could be skipped and would default to "", that is the
|
|
|
|
empty string. This is a very powerful feature to add optional text into
|
2010-08-20 04:04:55 -04:00
|
|
|
snippets.
|
2009-07-15 15:06:11 -04:00
|
|
|
|
|
|
|
4.7.2 Demos: *UltiSnips-demos*
|
|
|
|
|
|
|
|
The transformations are very powerful but yield often a convoluted snippet
|
|
|
|
syntax. Therefore I offer for each feature a simple example below.
|
|
|
|
|
|
|
|
This shows uppercasing one character
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet title "Titelize in the Transformation"
|
|
|
|
${1:a text}
|
|
|
|
${1/\w+\s*/\u$0/}
|
|
|
|
endsnippet
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
title<tab>big small ->
|
|
|
|
big small
|
|
|
|
Big small
|
|
|
|
|
|
|
|
|
|
|
|
This shows uppercasing one character and global replace:
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
snippet title "Titelize 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
|
|
|
|
|
|
|
|
This is a clever c-like printf snippet, the second tabstop is only shown
|
|
|
|
when there is a format (%) character in the first tab stop.
|
|
|
|
------------------- 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.
|
2009-07-15 14:11:47 -04:00
|
|
|
|
A "clearsnippets" feature
=========================
It's difficult for the user to control which of the default
bundled snippets are active in his environment. The
'runtimepath' variable must be set to the root of the ultisnips
installation, which brings in all of the bundled snippets.
Though the user may individually override the definition of the
bundled snippets using the "!" flag, the method has a couple of
problems:
- There's no way to remove a snippet, only to override it (and
each snippet must be overridden individually).
- The "!" flag currently doesn't remove the overridden snippets
from the "list snippets" command.
It might be considered a feature that "!" doesn't actually
remove the snippets from the "list snippets" command, though
perhaps that's an unintended effect. In any case, it would be
more convenient to allow the user to selectively remove the
bundled snippets from his environment.
A patch is provided in the following branch to address these problems:
http://code.launchpad.net/~drmikehenry/ultisnips/clearsnippets
The branch's primary purpose is the addition of a
"clearsnippets" command that may be placed in a user's
~/.vim/UltiSnips/ft.snippets file. The user may clear all
lower-priority snippet for that file type with the line:
clearsnippets
Alternatively, he may clear individual snippets by listing their
triggers:
clearsnippets trigger1 trigger2
A few changes were made to the testing system as part of the
incorporation of this new feature. These changes include:
- The "extends" directive is now supported on multiple lines
throughout file.
- A completely empty .snippets file is now possible.
- The test.py scripts now handles most of the vim setup,
simplifying the running of the tests. The invocation of Vim
now reduces to:
vim -u NONE
Instructions for running the tests are included at top of
test.py, where they should be more visible to interested
users; UltiSnips.vim now just points to test.py's
instructions.
- A new function vim_quote() encodes an arbitrary string into a
singly-quoted Vim string, with embedded quotes escaped.
- SnippetsFileParser() now allows file_data to be passed
directly for unit testing, avoiding the need to create files
in the filesystem for test purposes.
- A new _error() function reports errors to the user. At
runtime, this function uses :echo_err in general, but also can
append error text to current buffer to check for expected
errors during unit tests.
- Added error checks to snippets file parsing, along with unit
tests for the parsing.
- Increased retries from 2 to 4 (on my system, occasionally the
timing still causes tests to fail).
2009-09-08 20:15:10 -04:00
|
|
|
4.8 Clearing snippets *UltiSnips-clearing-snippets*
|
|
|
|
|
|
|
|
To remove snippets for the current file type, use the "clearsnippets"
|
|
|
|
directive:
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
clearsnippets
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
|
|
|
|
Without arguments, "clearsnippets" removes all snippets defined so far for the
|
|
|
|
current file type. UltiSnips travels in reverse along the 'runtimepath', so
|
|
|
|
"clearsnippets" removes snippet definitions appearing later in the
|
|
|
|
'runtimepath' than the ".snippets" file in which it's encountered.
|
|
|
|
|
|
|
|
Instead of clearing all snippets for the current file type, one or more
|
|
|
|
individual snippets may be cleared by specifying a space-separated list of
|
|
|
|
their triggers, e.g.:
|
|
|
|
|
|
|
|
------------------- SNIP -------------------
|
|
|
|
clearsnippets trigger1 trigger2
|
|
|
|
------------------- SNAP -------------------
|
|
|
|
|
2009-10-13 03:56:12 -04:00
|
|
|
This is useful if you only want to override a few triggers or all triggers
|
|
|
|
that came with UltiSnips with your own definitions. Note that you can
|
|
|
|
overwrite individual triggers when redefining them using the '!' option
|
2010-01-28 07:54:33 -05:00
|
|
|
(see |UltiSnips-adding-snippets| for the options).
|
2009-10-13 03:56:12 -04:00
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
=============================================================================
|
2010-08-20 04:03:09 -04:00
|
|
|
5. HELPING OUT *UltiSnips-helping*
|
2009-07-15 14:11:47 -04:00
|
|
|
|
2009-07-15 15:06:11 -04:00
|
|
|
UltiSnips needs the help of a vibrant vim community to make it more useful
|
|
|
|
tomorrow than it is today. Please consider joining this effort by providing
|
2010-08-20 04:04:55 -04:00
|
|
|
new snippets, new features or bug reports.
|
2009-07-15 15:06:11 -04:00
|
|
|
|
|
|
|
If you like this plugin, please also vote for it on its vim script page. It is
|
2010-08-20 04:04:55 -04:00
|
|
|
life changing for me, maybe it is for you too.
|
2009-07-17 19:32:07 -04:00
|
|
|
You can find the page here:
|
|
|
|
http://www.vim.org/scripts/script.php?script_id=2715
|
2009-07-13 06:28:58 -04:00
|
|
|
|
2009-07-13 04:46:14 -04:00
|
|
|
=============================================================================
|
2010-08-20 04:03:09 -04:00
|
|
|
6. CONTACT *UltiSnips-contact*
|
2009-07-13 04:46:14 -04:00
|
|
|
|
|
|
|
You can reach me at SirVer -AT- gmx -ADOT- de. You can find the launchpad
|
|
|
|
project for UltiSnips at https://launchpad.net/ultisnips/, there is also the
|
2010-08-20 04:04:55 -04:00
|
|
|
bug tracker.
|
2009-07-13 04:46:14 -04:00
|
|
|
|
2009-07-15 14:11:47 -04:00
|
|
|
This project aims to be the one-for-all solution for Snippets for Vim. If you
|
|
|
|
miss a feature or find a bug, please contact me or file a support ticket.
|
|
|
|
|
2009-08-16 10:07:34 -04:00
|
|
|
=============================================================================
|
2010-08-20 04:03:09 -04:00
|
|
|
7. CONTRIBUTORS *UltiSnips-contributors*
|
2009-08-16 10:07:34 -04:00
|
|
|
|
|
|
|
UltiSnips is mainly developed by SirVer (Holger Rapp). The following
|
|
|
|
individuals have contributed code to UltiSnips. In order of apperance.
|
|
|
|
|
2010-08-20 04:03:09 -04:00
|
|
|
7.1 Patches & Coding *UltiSnips-contricoding*
|
2009-08-16 10:07:34 -04:00
|
|
|
--------------------
|
|
|
|
|
2010-07-12 08:52:12 -04:00
|
|
|
Contributers are listed in chronological order:
|
|
|
|
|
|
|
|
JCEB - Jan Christoph Ebersbach
|
|
|
|
Michael Henry
|
|
|
|
Chris Chambers
|
2010-08-08 21:15:34 -04:00
|
|
|
Ryan Wooden
|
2010-11-13 05:25:01 -05:00
|
|
|
rupa - Rupa Deadwyler
|
2011-02-17 08:07:27 -05:00
|
|
|
Timo Schmiade
|
2011-03-14 15:19:35 -04:00
|
|
|
blueyed - Daniel Hahler
|
2011-03-28 14:27:54 -04:00
|
|
|
expelledboy - Anthony Jackson
|
2009-08-16 10:07:34 -04:00
|
|
|
|
2010-08-20 04:03:09 -04:00
|
|
|
7.2 Snippets *UltiSnips-contrisnippets*
|
2009-08-16 10:07:34 -04:00
|
|
|
------------
|
|
|
|
|
2010-07-12 08:52:12 -04:00
|
|
|
Contributers are listed in chronological order:
|
|
|
|
|
2011-03-28 14:27:54 -04:00
|
|
|
Alec Thomas
|
2010-08-08 21:15:34 -04:00
|
|
|
Ryan Wooden
|
2010-12-06 08:27:33 -05:00
|
|
|
Ches Martin
|
2011-01-12 07:19:19 -05:00
|
|
|
Gordin (g0rdin)
|
2009-08-16 10:07:34 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
2009-07-13 06:28:58 -04:00
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|
2009-08-16 10:07:34 -04:00
|
|
|
|