mirror of
https://github.com/gryf/snipmate.vim.git
synced 2025-12-30 18:32:31 +01:00
301 lines
13 KiB
Plaintext
301 lines
13 KiB
Plaintext
*snipMate.txt* Plugin for using TextMate-style snippets in Vim.
|
|
|
|
snipMate *snippet* *snippets* *snipMate*
|
|
Last Change: March 15, 2009
|
|
|
|
|snipMate-description| Description
|
|
|snipMate-usage| Usage
|
|
|snipMate-syntax| Snippet syntax
|
|
|snipMate-features| Features
|
|
|snipMate-disadvantages| Disadvantages to TextMate
|
|
|snipMate-contact| Contact
|
|
|
|
For Vim version 7.0 or later.
|
|
This plugin only works if 'compatible' is not set.
|
|
{Vi does not have any of these features.}
|
|
|
|
==============================================================================
|
|
DESCRIPTION *snipMate-description*
|
|
|
|
snipMate.vim implements some of TextMate's snippets features in
|
|
Vim. A snippet is a piece of often-typed text that you can
|
|
insert into your document using a trigger word followed by a <tab>.
|
|
|
|
For instance, in a C file using the default installation of
|
|
snipMate.vim, if you type "for<tab>" in insert mode,
|
|
it will expand a typical for loop in C: >
|
|
|
|
for (i = 0; i < count; i++) {
|
|
|
|
}
|
|
|
|
|
|
To go to the next item in the loop, simply <tab>
|
|
over to it; if there is repeated code, such as the "i" variable
|
|
in this example, you can simply start typing once it's
|
|
highlighted and all the matches specified in the snippet will
|
|
be updated.
|
|
|
|
==============================================================================
|
|
USAGE *snipMate-usage*
|
|
|
|
There are currently two ways to make snippets: file-based and command-based.
|
|
File-based snippets are simply *.snippet files named after the trigger of
|
|
the snippet placed in the directory of the filetype
|
|
(<filetype>/<trigger>.snippet); command-based snippets are snippets defined
|
|
using the |Snipp| , |BufferSnip|, and |GlobalSnip| commands. File-based
|
|
snippets have the advantage of being easier to read, but do not support
|
|
special characters in snippet triggers, while command-based snippets are
|
|
obviously convenient for short snippets but can quickly get unreadable.
|
|
|
|
*command-snippets*
|
|
------------------------------------------------------------------------------
|
|
Command Snippets~
|
|
|
|
Command-based snippets should be installed in the 'after' directory, typically
|
|
located in '~/.vim/after' (see |vimfiles|). Filetype specific snippets should
|
|
be installed in 'after/ftplugin', such as 'after/ftplugin/<filetype>_snips.vim'.
|
|
See |ftplugins|. Global snippets should be installed in 'after/plugin'.
|
|
To ensure user snippets are not lost when upgrading the plugin, name them
|
|
using an ending other than "snips" such as "<filetype>_mysnips.vim"
|
|
|
|
*g:snippet_filetype* *snippet_filetype*
|
|
Partly due to the addition of file-based snippets, it is now necessary to
|
|
define the current filetype for snippets at the top of command-based snippet
|
|
files. For instance, at the top of the 'c_snips.vim' file included with
|
|
snipMate: >
|
|
|
|
let snippet_filetype = 'c'
|
|
|
|
This ensures dotted filetypes (see 'filetype') are dealt with correctly.
|
|
|
|
*Snipp* *BufferSnip* *GlobalSnip*
|
|
Snipp, BufferSnip, and GlobalSnip Commands~
|
|
|
|
Snippets are added via the "Snipp" and "GlobalSnip" commands. The syntax for
|
|
these are "Snipp <trigger> <text>"; e.g.: >
|
|
|
|
exe "Snipp trigger The cursor will be placed at the end of this sentence."
|
|
exe "GlobalSnip another_trigger foo"
|
|
exe "BufferSnip bar This snippet only works for the current buffer."
|
|
|
|
"Snipp" creates snippets for the current filetype, "GlobalSnip" creates global
|
|
snippets, and "BufferSnip" creates snippets for the current buffer. "Snipp"
|
|
is used instead of "Snip" to avoid conflicts with the imaps.vim vim script
|
|
that uses that command name.
|
|
|
|
These commands are conveniently bound to snippets themselves; "snip", "bsnip",
|
|
and "gsnip", respectively (in vim files). So to expand a Snipp command with
|
|
double quotes, just type snip<tab>. Single quote Snipp and GlobalSnip
|
|
commands are bound to the snippets "snipp", "bsnipp" and "gsnipp". See
|
|
|literal-string| for the difference between single and double quotes.
|
|
|
|
*multi_snip* *Snipp!* *BufferSnip!* *GlobalSnip!*
|
|
To specify that a snippet can have multiple matches, use the Snipp,
|
|
BufferSnip, or GlobalSnip command followed by a bang (!). The syntax for these
|
|
are 'Snipp! <trigger> "<name>" <text>'. (Note that the name must be enclosed
|
|
in double quotes). E.g.: >
|
|
|
|
exe 'Snipp! trigger "Snippet name #1" expand_this_text'
|
|
exe 'Snipp! trigger "Snippet name #2" expand_THIS_text!'
|
|
|
|
In this example, when "trigger<tab>" is typed, a numbered menu containing all
|
|
of the names for the "trigger" will be shown; when the user presses the
|
|
corresponding number, that snippet will then be expanded.
|
|
|
|
To create a create a snippet with multiple matches using file-based snippets,
|
|
simply place all the snippets in a subdirectory with the trigger name, i.e.
|
|
'snippets/<filetype>/<trigger>/<name>.snippet'.
|
|
|
|
To ensure snipMate.vim is loaded, 'compatible' is not set, and your snippet
|
|
file is only loaded once make sure to add: >
|
|
|
|
if !exists('g:loaded_snips') || exists('s:did_my_snips')
|
|
finish
|
|
endif
|
|
let s:did_my_snips = 1
|
|
|
|
to the top of your snippets files. The snippet "guard" comes with snipMate to
|
|
automate this if you'd rather not type it all out.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
*file-snippets*
|
|
File Snippets ~
|
|
------------------------------------------------------------------------------
|
|
|
|
*'snippets'* *g:snippets_dir*
|
|
File-based snippets are by default looked for in the 'snippets' directory
|
|
inside your home '.vim' directory, typically located in
|
|
'~/.vim/snippets/<filetype>' on *nix or '$HOME\vimfiles\snippets\<filetype>'
|
|
on Windows. To change that location or add another one, change the
|
|
g:snippets_dir variable in your |.vimrc| to your preferred directory, or use
|
|
the |ExtractSnips()|function. NOTE: g:snippets_dir must end in a backslash or
|
|
forward slash.
|
|
|
|
File-based snippets have the same syntax as command-based snippets; just make
|
|
sure to use hard tabs instead of spaces in the files for indenting. They can
|
|
be automatically converted later if desired (see |snipMate-indenting|).
|
|
|
|
ExtractSnips({directory}, {filetype}) *ExtractSnips()*
|
|
|
|
ExtractSnips() extracts *.snippet files from the specified directory and
|
|
defines them as snippets for the given filetype; to define a global snippet,
|
|
use '_' for the {filetype} argument.
|
|
|
|
*ResetSnips()*
|
|
The ResetSnips() function removes all snippets from memory. This is useful to
|
|
put at the top of a snippet setup file for file-based snippets if you would
|
|
like to |:source| it multiple times.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
==============================================================================
|
|
SYNTAX *snipMate-syntax* *snipMate-${#}*
|
|
|
|
Tab stops ~
|
|
|
|
By default, the cursor is placed at the end of a snippet. To specify where the
|
|
cursor is to be placed next, use "${#}", where the # is the number of the tab
|
|
stop. E.g., to place the cursor first on the id of a <div> tag, and then allow
|
|
the user to press <tab> to go to the middle of it:
|
|
>
|
|
exe "Snipp div <div id=\"${1}\">\n\t${2}\n</div>"
|
|
<
|
|
*snipMate-placeholders* *snipMate-${#:}* *snipMate-$#*
|
|
Placeholders ~
|
|
|
|
Placeholder text can be supplied using "${#:text}", where # is the number of
|
|
the tab stop. This text then can be copied throughout the snippet using "$#",
|
|
given # is the same number as used before. So, to make a C for loop: >
|
|
|
|
exe "Snipp for for (${2:i}; $2 < ${1:count}; $1++) {\n\t${4}\n}"
|
|
|
|
This will cause "count" to first be selected and change if the user starts
|
|
typing. When <tab> is pressed, the "i" in ${2}'s position will be selected;
|
|
all $2 variables will default to "i" and automatically be updated if the user
|
|
starts typing.
|
|
NOTE: "$#" syntax is used only for variables, not for tab stops as in TextMate.
|
|
|
|
Variables within variables are also possible. For instance: >
|
|
|
|
exe 'Snipp opt <option value="${1:option}">${2:$1}</option>'
|
|
|
|
Will, as usual, cause "option" to first be selected and update all the $1
|
|
variables if the user starts typing. Since one of these variables is inside of
|
|
${2}, this text will then be used as a placeholder for the next tab stop,
|
|
allowing the user to change it if he wishes.
|
|
|
|
To copy a value throughout a snippet without supplying default text, simply
|
|
use the "${#:}" construct without the text; e.g.: >
|
|
|
|
exe 'Snipp foo${1:}bar$1'
|
|
< *snipMate-commands*
|
|
Interpolated Vim Script ~
|
|
|
|
Snippets can also contain Vim script commands that are executed (via |eval()|)
|
|
when the snippet is inserted. Commands are given inside backticks (`...`); for
|
|
TextMates's functionality, use the |system()| function. E.g.: >
|
|
|
|
exe 'Snipp date `system("date +%Y-%m-%d")`'
|
|
|
|
will insert the current date, assuming you are on a Unix system. Note that you
|
|
can also (and should) use |strftime()| for this example.
|
|
|
|
Filename([{expr}] [, {defaultText}]) *snipMate-filename* *Filename()*
|
|
|
|
Since the current filename is used often in snippets, a default function
|
|
has been defined for it in snipMate.vim, appropriately called Filename().
|
|
|
|
With no arguments, the default filename without an extension is returned;
|
|
the first argument specifies what to place before or after the filename,
|
|
and the second argument supplies the default text to be used if the file
|
|
has not been named. "$1" in the first argument is replaced with the filename;
|
|
if you only want the filename to be returned, the first argument can be left
|
|
blank. Examples: >
|
|
|
|
exe 'Snipp filename `Filename()`'
|
|
exe 'Snipp filename_with_default `Filename("", "name")`'
|
|
exe 'Snipp filename_foo `Filename("$1_foo")`'
|
|
|
|
|
|
The first example returns the filename if it the file has been named, and an
|
|
empty string if it hasn't. The second returns the filename if it's been named,
|
|
and "name" if it hasn't. The third returns the filename followed by "_foo" if
|
|
it has been named, and an empty string if it hasn't.
|
|
|
|
*snipMate-settings* *g:snips_author*
|
|
The g:snips_author string (similar to $TM_FULLNAME in TextMate) should be set
|
|
to your name; it can then be used in snippets to automatically add it. E.g.: >
|
|
|
|
let g:snips_author = 'Hubert Farnsworth'
|
|
exe 'Snipp name `g:snips_author`'
|
|
<
|
|
|
|
*snipMate-expandtab* *snipMate-indenting*
|
|
If you would like your snippets to use spaces instead of tabs, just enable
|
|
'expandtab' and set 'softtabstop' to your preferred amount of spaces. If
|
|
'softtabstop' is not set, 'shiftwidth' is used instead.
|
|
|
|
*snipMate-remap*
|
|
snipMate does not come with a setting to customize the trigger key, but you
|
|
can remap it easily in the two lines it's defined in the 'after' directory
|
|
under 'plugin/snipMate.vim'. For instance, to change the trigger key
|
|
to shift-tab, just change this: >
|
|
|
|
ino <tab> <c-r>=ExpandSnippet()<cr>
|
|
snor <tab> <esc>i<right><c-r>=ExpandSnippet()<cr>
|
|
|
|
to this: >
|
|
ino <s-tab> <c-r>=ExpandSnippet()<cr>
|
|
snor <s-tab> <esc>i<right><c-r>=ExpandSnippet()<cr>
|
|
|
|
==============================================================================
|
|
FEATURES *snipMate-features*
|
|
|
|
snipMate.vim has the following features among others:
|
|
- The syntax of snippets is very similar to TextMate's, allowing
|
|
easy conversion.
|
|
- The position of the snippet is kept transparently (i.e. it does not use
|
|
markers/placeholders written to the buffer), which allows you to escape
|
|
out of an incomplete snippet, something particularly useful in Vim.
|
|
- Variables in snippets are updated as-you-type.
|
|
- Snippets can have multiple matches.
|
|
- Snippets can be out of order. For instance, in a do...while loop, the
|
|
condition can be added before the code.
|
|
- (New) File-based snippets are supported.
|
|
- (New) Triggers after non-word delimiters are expanded, e.g. "foo"
|
|
in "bar.foo".
|
|
- (New) Nested snippets are possible.
|
|
|
|
==============================================================================
|
|
DISADVANTAGES *snipMate-disadvantages*
|
|
|
|
snipMate.vim currently has the following disadvantages to TextMate's snippets:
|
|
- There is no way to go back a tab stop, like shift-tab in TextMate.
|
|
- There is no $0; the order of tab stops must be explicitly stated.
|
|
- Placeholders within placeholders are not possible. E.g.: >
|
|
|
|
'<div${1: id="${2:some_id}}">${3}</div>'
|
|
<
|
|
In TextMate this would first highlight ' id="some_id"', and if
|
|
you hit delete it would automatically skip ${2} and go to ${3}
|
|
on the next <tab>, but if you didn't delete it it would highlight
|
|
"some_id" first. You cannot do this in snipMate.vim.
|
|
- Regex cannot be performed on variables, such as "${1/.*/\U&}"
|
|
- Placeholders cannot span multiple lines.
|
|
- Activating snippets in different scopes of the same file is
|
|
not possible.
|
|
|
|
Perhaps some of these features will be added in a later release.
|
|
|
|
==============================================================================
|
|
CONTACT *snipMate-contact* *snipMate-author*
|
|
|
|
To contact the author (Michael Sanders), please email:
|
|
msanders42+snipmate <at> gmail <dot> com
|
|
|
|
I greatly appreciate any suggestions or improvements offered for the script.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|