doc/UltiSnips.txt

*UltiSnips.txt*    For Vim version 8.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-install-and-update|
3. Settings & Commands                          |UltiSnips-settings|
   3.1 Commands                                 |UltiSnips-commands|
      3.1.1 UltiSnipsEdit                       |UltiSnipsEdit|
      3.1.2 UltiSnipsAddFiletypes               |UltiSnipsAddFiletypes|
   3.2 Triggers                                 |UltiSnips-triggers|
      3.2.1 Trigger key mappings                |UltiSnips-trigger-key-mappings|
      3.2.2 Using your own trigger functions    |UltiSnips-trigger-functions|
      3.2.3 Custom autocommands                 |UltiSnips-custom-autocommands|
      3.2.4 Direct use of Python API            |UltiSnips-use-python-api|
   3.3 Warning About Select Mode Mappings       |UltiSnips-warning-smappings|
   3.4 Functions                                |UltiSnips-functions|
      3.4.1 UltiSnips#AddSnippetWithPriority    |UltiSnips#AddSnippetWithPriority|
      3.4.2 UltiSnips#Anon                      |UltiSnips#Anon|
      3.4.3 UltiSnips#SnippetsInCurrentScope    |UltiSnips#SnippetsInCurrentScope|
      3.4.4 UltiSnips#CanExpandSnippet          |UltiSnips#CanExpandSnippet|
      3.4.5 UltiSnips#CanJumpForwards           |UltiSnips#CanJumpForwards|
      3.4.6 UltiSnips#CanJumpBackwards          |UltiSnips#CanJumpBackwards|
   3.5 Missing python support                   |UltiSnips-python-warning|
4. Authoring snippets                           |UltiSnips-authoring-snippets|
   4.1 Basics                                   |UltiSnips-basics|
      4.1.1 How snippets are loaded             |UltiSnips-how-snippets-are-loaded|
      4.1.2 Basic syntax                        |UltiSnips-basic-syntax|
      4.1.3 Snippet Options                     |UltiSnips-snippet-options|
      4.1.4 Character Escaping                  |UltiSnips-character-escaping|
      4.1.5 Snippets text-objects               |UltiSnips-snippet-text-objects|
   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 Custom context snippets                  |UltiSnips-custom-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. Debugging                                    |UltiSnips-Debugging|
7. FAQ                                          |UltiSnips-FAQ|
8. Helping Out                                  |UltiSnips-helping|
9. Contributors                                 |UltiSnips-contributors|

This plugin only works if 'compatible' is not set.
{Vi does not have any of these features}
{only available when |+python3| has 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 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 8.0 or later with Python 3 support enabled.
It only works if the 'compatible' setting is not set.

The Python 3.x interface must be available. In other words, Vim
must be compiled with 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 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.


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-install-and-update*

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 Vim 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. An excellent selection of snippets can be
found here: https://github.com/honza/vim-snippets

=============================================================================
3. Settings & Commands                                   *UltiSnips-settings*

3.1 Commands                                             *UltiSnips-commands*
------------

 3.1.1 UltiSnipsEdit                                     *: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 that exist 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.
                            |tabdo|          Opens the window in a new tab.
                            |horizontal|     Splits the window horizontally.
                            |vertical|       Splits the window vertically.
                            |context|        Splits the window vertically or
                                           horizontally depending on context.

                                                        *g:UltiSnipsSnippetStorageDirectoryForUltiSnipsEdit*
g:UltiSnipsSnippetStorageDirectoryForUltiSnipsEdit
                            A single absolute path to a directory which will
                            be used as the storage for location for
                            `UltiSnipsEdit`. This means that UltiSnipsEdit no
                            longer searches all paths in
                            `g:UltiSnipsSnippetDirectories` for snippets to
                            edit, but only this one. Note that this does not
                            imply that the snippet expansion engine also
                            searches this directory. Please read
                            |UltiSnips-how-snippets-are-loaded| for details.


                                                        *g:UltiSnipsSnippetDirectories*
g:UltiSnipsSnippetDirectories
                            An array of relative directory names OR an array
                            with a single absolute path. Defaults to [
                            "UltiSnips" ]. No entry in this list must be
                            "snippets". Please read
                            |UltiSnips-how-snippets-are-loaded| for details.

                                                        *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.


 3.1.2 UltiSnipsAddFiletypes                            *: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. For example 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*
------------

 3.2.1 Trigger key mappings                   *UltiSnips-trigger-key-mappings*

                           *g:UltiSnipsExpandTrigger* *g:UltiSnipsListSnippets*
               *g:UltiSnipsJumpForwardTrigger* *g:UltiSnipsJumpBackwardTrigger*
              *g:UltiSnipsExpandOrJumpTrigger* *g:UltiSnipsJumpOrExpandTrigger*

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> (and others, like <c-h>) 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>

If you prefer to use the same trigger for expanding snippets and jumping
forward, g:UltiSnipsExpandOrJumpTrigger and g:UltiSnipsJumpOrExpandTrigger
variables are what you want. Try to set g:UltiSnipsExpandOrJumpTrigger if
you give priority to expanding snippets. It'll expand snippets first when
you are in a position where you can both expand snippets and jump forward. >
   let g:UltiSnipsExpandOrJumpTrigger = "<tab>"

Or else, if you have a preference for jumping forward first, set
g:UltiSnipsJumpOrExpandTrigger instead. >
   let g:UltiSnipsJumpOrExpandTrigger = "<tab>"

If both g:UltiSnipsExpandOrJumpTrigger and g:UltiSnipsJumpOrExpandTrigger
is set, g:UltiSnipsExpandOrJumpTrigger variable will take effects.

3.2.2 Using your own trigger functions           *UltiSnips-trigger-functions*

For advanced users there are 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
   g:UltiSnipsExpandOrJumpTrigger  <--> UltiSnips#ExpandSnippetOrJump
   g:UltiSnipsJumpOrExpandTrigger  <--> UltiSnips#JumpOrExpandSnippet

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#JumpOrExpandSnippet,
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#JumpOrExpandSnippet --> 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.3 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
snippet 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.4 Direct use of Python API                   *UltiSnips-use-python-api*

For even more advanced usage, you can directly write python functions using
UltiSnip's python modules. This is an internal and therefore unstable API and
not recommended though.

Here is a small example function 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 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.4 Functions                                           *UltiSnips-functions*
-------------

UltiSnips provides some functions for extending core functionality.


 3.4.1 UltiSnips#AddSnippetWithPriority    *UltiSnips#AddSnippetWithPriority*

The first function is UltiSnips#AddSnippetWithPriority(trigger, value, description,
options, filetyp, priority). It adds a new snippet to the current list of
snippets. See |UltiSnips-authoring-snippets| for details most of the function
arguments. The priority is a number that defines which snippet should be
preferred over others. See the priority keyword in |UltiSnips-basic-syntax|.


 3.4.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. A more elegant way of
creating such a snippet could be to use |UltiSnips-autotrigger|.

 3.4.3 UltiSnips#SnippetsInCurrentScope    *UltiSnips#SnippetsInCurrentScope*

UltiSnips#SnippetsInCurrentScope returns a vim dictionary with the snippets
whose trigger matches the current word.  If you need all snippets information
for the current buffer, you can simply pass 1 (which means all) as first
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.
For example, all completion plugins that integrate with UltiSnips use this
function.

Another 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.

One more example on how to use this function to extract all snippets available
in the 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

 3.4.4 UltiSnips#CanExpandSnippet    *UltiSnips#CanExpandSnippet*

This function returns 1 if UltiSnips can actually do a meaningful expansion in
the current situation. This is useful in conditional mappings.

 3.4.5 UltiSnips#CanJumpForwards    *UltiSnips#CanJumpForwards*

This function returns 1 if UltiSnips can jump forward in the current
situation. This is useful in conditional mappings.

 3.4.6 UltiSnips#CanJumpBackwards    *UltiSnips#CanJumpBackwards*

This function returns 1 if UltiSnips can jump backwards in the current
situation. This is useful in conditional mappings.

 3.4.7 UltiSnips#ToggleAutoTrigger              *UltiSnips#ToggleAutoTrigger*

This function toggles the `autotrigger` functionality. Its return value
corresponds to the new state of the `autotrigger` (0: disabled, 1: enabled).

For example, the following mapping can be used to toggle the `autotrigger`
in the Insert mode: >
    inoremap <silent> <C-t> <CMD>call UltiSnips#ToggleAutoTrigger()<CR>
<
                                                    *g:UltiSnipsAutoTrigger*
By default, `autotrigger` is enabled (relevant for snippets with the option 'A').
If you want to disable it by default, add the following line to your vimrc: >
    let g:UltiSnipsAutoTrigger = 0


3.5 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. Authoring snippets                             *UltiSnips-authoring-snippets*

4.1 Basics                                        *UltiSnips-basics*
----------

 4.1.1 How snippets are loaded               *UltiSnips-how-snippets-are-loaded*

Snippet definition files are stored in snippet directories. The main
controlling variable for where these directories are searched for is the
list variable, set by default to >

   let g:UltiSnipsSnippetDirectories=["UltiSnips"]

Note that "snippets" is reserved for snipMate snippets and cannot be used in
this list. Whether snipMate snippets are active or not is controlled by the
variable `g:UltiSnipsEnableSnipMate`.

UltiSnips will search each 'runtimepath' directory for the subdirectory names
defined in g:UltiSnipsSnippetDirectories in the order they are defined. For
example, if you keep your snippets in `~/.vim/mycoolsnippets` and you want to
make use of the UltiSnips snippets that come with other plugins, add the
following to your vimrc file. >

   let g:UltiSnipsSnippetDirectories=["UltiSnips", "mycoolsnippets"]

If you do not want to use the third party snippets that come with plugins,
define the variable accordingly: >

   let g:UltiSnipsSnippetDirectories=["mycoolsnippets"]

If the list has only one entry that is an absolute path, UltiSnips will not
iterate through &runtimepath but only look in this one directory for snippets.
This can lead to significant speedup. This means you will miss out on snippets
that are shipped with third party plugins. You'll need to copy them into this
directory manually.

An example configuration could be: >

    let g:UltiSnipsSnippetDirectories=[$HOME.'/.vim/UltiSnips']

You can also redefine the search path on a buffer by buffer basis by setting
the variable b:UltiSnipsSnippetDirectories. This variable takes precedence
over the global variable.

There is an additional variable which does not control the search path for
snippets at expansion time, but controls where `:UltiSnipsEdit` is looking for
snippets. If this variable is set to a single absolute path it will only
affect where the edit command is looking for and writing snippets too. This is
useful if you want to use third party snippets, but have all your self created
snippets in a single place without being asked where to put the file on edit.

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.

 4.1.2 Basic syntax                                     *UltiSnips-basic-syntax*

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 a 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 trigger_word [ "description" [ options ] ]

The trigger_word is required, but the description and options are optional.

The 'trigger_word' is the word or string sequence used to trigger the snippet.
Generally a single word is used but the trigger_word can include spaces. If you
wish to include spaces, you must wrap the tab trigger in quotes. >

    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.


 4.1.3 Snippet Options:                           *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. This option overrides 'i'.

   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". Regular expression snippets
       can be triggered in-word by default. To avoid this you can start your
       regex pattern with '\b', although this will not respect your
       'iskeyword' setting.

   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.

   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   Custom context snippet - 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-custom-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.4 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.1.5 Snippets text-objects                   *UltiSnips-snippet-text-objects*

Inside a snippets buffer, the following text objects are available:
>
   iS   inside snippet
   aS   around snippet (including empty lines that follow)


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 in the same Vim instance. You can use |UltiSnipsEdit| for this,
but you can also just run >
   :tabedit ~/.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 also in another way. Generally when a snippet is
expanded the standard output of code replaces the code. With python code the
value of the 'snip.rv' property 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 and owns the string that
             should be inserted for the snippet.
   context - Result of context condition. See |UltiSnips-custom-context-snippets|.
   match   - Only in regular expression triggered snippets. This is the return
             value of the match of the regular expression. See
             http://docs.python.org/library/re.html#match-objects

The 'snip' object provides the following methods: >

    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. This 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. 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 the 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 it is
commonly used for completion. See |UltiSnips-triggers| for help on defining
different keys for motions.

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}}"
        $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>

Another special type of tabstop is choice tabstop. It let's you to choose
from a predefined list of items. The syntax of a choice tabstop is >
    ${1|item1,item2,item3,...|}
Here is an example to illustrate this feature.

------------------- SNIP -------------------
>
    snippet q
    Your age: ${1|<18,18~60,>60|}
    Your height: ${2|<120cm,120cm~180cm,>180cm|}
    endsnippet
<
------------------- SNAP -------------------

q<tab>2<c-j>2
Your age: 18~60
Your height: 120cm~180cm

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
vim-snippets repo.


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 Custom context snippets                      *UltiSnips-custom-context-snippets*

Custom context snippets can be enabled by using the 'e' option in the snippet
definition.

In that case snippet should be defined using this syntax: >

    snippet trigger_word "description" "expression" options

The context can also be defined using a special header: >

    context "python_expression"
    snippet trigger_word "description" options

The 'expression' can be any python expression. If 'expression' evaluates to
'True', then this snippet will be eligible 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.before' - contains the text in the current line up to and including
        the matched snippet. Since 'snip.column' counts bytes, not characters,
        this is **not** equivalent to 'snip.buffer[snip.line][:snip.column+1]'.
        This property is only available in the scope of contexts but not in
        that of actions.


For regular expression triggered snippets the variable `match` will contain
the return value of the match of the regular expression. See http://docs.python.org/library/re.html#match-objects.

------------------- 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: custom context snippets are prioritized over other snippets. It makes possible
to use other snippets as a fallback if no context can be 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 the 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 the previous snippet by using the
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*
---------------------

A snippet action is an arbitrary python code which can be executed at specific
points in the lifetime of a snippet expansion.

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
  were applied for the first time, but before jump on the first placeholder.
* Jump - invoked just after a 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-custom-context-snippets| section (except 'snip.before').

                                                *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
in that case UltiSnips will not be able to track changes to the buffer
correctly.

'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(snip.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), and 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*
----------------

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 the snippet
will be triggered.

*Warning:* using of this feature might lead to significant vim slowdown. If
you discovered that, please report an issue.

If you want to temporarily disable autotriggering, the `autotrigger` behavior
can be toggled via |UltiSnips#ToggleAutoTrigger|. By default it is enabled,
but it is possible to customize it with |g:UltiSnipsAutoTrigger|.

Consider following useful Go snippets:
------------------- 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 the 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. 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.

deoplete - The successor of neocomplete is also supported. The completion 
source is called 'ultisnips'.

vim-easycomplete - Vim-EasyComplete needs ultisnips and vim-snippets for 
snippets support. This two plugin is compatible with EasyComplete out of
the box. More information: <https://github.com/jayli/vim-easycomplete>

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/test_UltiSnipsFunc.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. Debugging                                            *UltiSnips-Debugging*

UltiSnips comes with a remote debugger disabled
by default. When authoring a complex snippet
with python code, you may want to be able to
set breakpoints to inspect variables.
It is also useful when debugging UltiSnips itself.

See |UltiSnips-Advanced-Debugging| for more informations

=============================================================================
7. FAQ                                                        *UltiSnips-FAQ*

Q: Do I have to call UltiSnips#ExpandSnippet() to check if a snippet is
   expandable? Is there instead an analog of neosnippet#expandable?
A: Yes there is, try

  function UltiSnips#IsExpandable()
    return !empty(UltiSnips#SnippetsInCurrentScope())
  endfunction

  Consider that UltiSnips#SnippetsInCurrentScope() will return all the
  snippets you have if you call it after a space character. If you want
  UltiSnips#IsExpandable() to return false when you call it after a space
  character use this a bit more complicated implementation:

  function UltiSnips#IsExpandable()
    return !(
      \ col('.') <= 1
      \ || !empty(matchstr(getline('.'), '\%' . (col('.') - 1) . 'c\s'))
      \ || empty(UltiSnips#SnippetsInCurrentScope())
      \ )
  endfunction

=============================================================================
8. 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

=============================================================================
9. Contributors                                      *UltiSnips-contributors*

UltiSnips has been started and maintained from Jun 2009 - Dec 2015 by Holger
Rapp (@SirVer, SirVer@gmx.de). Up to April 2018 it was maintained by Stanislav
Seletskiy (@seletskiy). Now, it is maintained by a growing set of
contributors.

This is the list of contributors pre-git in chronological order. For a full
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: