287 lines
12 KiB
Text
287 lines
12 KiB
Text
|
*snipMate.txt* Plugin for using TextMate-style snippets in Vim.
|
||
|
|
|
||
|
|
snipMate *snippet* *snippets* *snipMate*
|
||
|
|
Last Change: July 13, 2009
|
||
|
|
|
||
|
|
|snipMate-description| Description
|
||
|
|
|snipMate-syntax| Snippet syntax
|
||
|
|
|snipMate-usage| Usage
|
||
|
|
|snipMate-settings| Settings
|
||
|
|
|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. To go in reverse, use <shift-tab>.
|
||
|
|
|
||
|
|
==============================================================================
|
||
|
|
SYNTAX *snippet-syntax*
|
||
|
|
|
||
|
|
Snippets can be defined in two ways. They can be in their own file, named
|
||
|
|
after their trigger in 'snippets/<filetype>/<trigger>.snippet', or they can be
|
||
|
|
defined together in a 'snippets/<filetype>.snippets' file. Note that dotted
|
||
|
|
'filetype' syntax is supported -- e.g., you can use >
|
||
|
|
|
||
|
|
:set ft=html.eruby
|
||
|
|
|
||
|
|
to activate snippets for both HTML and eRuby for the current file.
|
||
|
|
|
||
|
|
The syntax for snippets in *.snippets files is the following: >
|
||
|
|
|
||
|
|
snippet trigger
|
||
|
|
expanded text
|
||
|
|
more expanded text
|
||
|
|
|
||
|
|
Note that the first hard tab after the snippet trigger is required, and not
|
||
|
|
expanded in the actual snippet. The syntax for *.snippet files is the same,
|
||
|
|
only without the trigger declaration and starting indentation.
|
||
|
|
|
||
|
|
Also note that snippets must be defined using hard tabs. They can be expanded
|
||
|
|
to spaces later if desired (see |snipMate-indenting|).
|
||
|
|
|
||
|
|
"#" is used as a line-comment character in *.snippets files; however, they can
|
||
|
|
only be used outside of a snippet declaration. E.g.: >
|
||
|
|
|
||
|
|
# this is a correct comment
|
||
|
|
snippet trigger
|
||
|
|
expanded text
|
||
|
|
snippet another_trigger
|
||
|
|
# this isn't a comment!
|
||
|
|
expanded text
|
||
|
|
<
|
||
|
|
This should hopefully be obvious with the included syntax highlighting.
|
||
|
|
|
||
|
|
*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:
|
||
|
|
>
|
||
|
|
snippet div
|
||
|
|
<div id="${1}">
|
||
|
|
${2}
|
||
|
|
</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: >
|
||
|
|
|
||
|
|
snippet for
|
||
|
|
for (${2:i}; $2 < ${1:count}; $1++) {
|
||
|
|
${4}
|
||
|
|
}
|
||
|
|
|
||
|
|
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: >
|
||
|
|
|
||
|
|
snippet 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.: >
|
||
|
|
|
||
|
|
snippet 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.: >
|
||
|
|
|
||
|
|
snippet 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: >
|
||
|
|
|
||
|
|
snippet filename
|
||
|
|
`Filename()`
|
||
|
|
snippet filename_with_default
|
||
|
|
`Filename('', 'name')`
|
||
|
|
snippet 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.
|
||
|
|
|
||
|
|
*multi_snip*
|
||
|
|
To specify that a snippet can have multiple matches in a *.snippets file, use
|
||
|
|
this syntax: >
|
||
|
|
|
||
|
|
snippet trigger A description of snippet #1
|
||
|
|
expand this text
|
||
|
|
snippet trigger A description of snippet #2
|
||
|
|
expand THIS text!
|
||
|
|
|
||
|
|
In this example, when "trigger<tab>" is typed, a numbered menu containing all
|
||
|
|
of the descriptions of the "trigger" will be shown; when the user presses the
|
||
|
|
corresponding number, that snippet will then be expanded.
|
||
|
|
|
||
|
|
To create a snippet with multiple matches using *.snippet files,
|
||
|
|
simply place all the snippets in a subdirectory with the trigger name:
|
||
|
|
'snippets/<filetype>/<trigger>/<name>.snippet'.
|
||
|
|
|
||
|
|
==============================================================================
|
||
|
|
USAGE *snipMate-usage*
|
||
|
|
|
||
|
|
*'snippets'* *g:snippets_dir*
|
||
|
|
Snippets are by default looked for any 'snippets' directory in your
|
||
|
|
'runtimepath'. Typically, it is located at '~/.vim/snippets/' on *nix or
|
||
|
|
'$HOME\vimfiles\snippets\' 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. This will be used by the
|
||
|
|
|globpath()| function, and so accepts the same syntax as it (e.g.,
|
||
|
|
comma-separated paths).
|
||
|
|
|
||
|
|
ExtractSnipsFile({directory}, {filetype}) *ExtractSnipsFile()* *.snippets*
|
||
|
|
|
||
|
|
ExtractSnipsFile() extracts the specified *.snippets file for the given
|
||
|
|
filetype. A .snippets file contains multiple snippet declarations for the
|
||
|
|
filetype. It is further explained above, in |snippet-syntax|.
|
||
|
|
|
||
|
|
ExtractSnips({directory}, {filetype}) *ExtractSnips()* *.snippet*
|
||
|
|
|
||
|
|
ExtractSnips() extracts *.snippet files from the specified directory and
|
||
|
|
defines them as snippets for the given filetype. The directory tree should
|
||
|
|
look like this: 'snippets/<filetype>/<trigger>.snippet'. If the snippet has
|
||
|
|
multiple matches, it should look like this:
|
||
|
|
'snippets/<filetype>/<trigger>/<name>.snippet' (see |multi_snip|).
|
||
|
|
|
||
|
|
*ResetSnippets()*
|
||
|
|
The ResetSnippets() function removes all snippets from memory. This is useful
|
||
|
|
to put at the top of a snippet setup file for if you would like to |:source|
|
||
|
|
it multiple times.
|
||
|
|
|
||
|
|
*list-snippets* *i_CTRL-R_<Tab>*
|
||
|
|
If you would like to see what snippets are available, simply type <c-r><tab>
|
||
|
|
in the current buffer to show a list via |popupmenu-completion|.
|
||
|
|
|
||
|
|
==============================================================================
|
||
|
|
SETTINGS *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'
|
||
|
|
snippet name
|
||
|
|
`g:snips_author`
|
||
|
|
<
|
||
|
|
*snipMate-expandtab* *snipMate-indenting*
|
||
|
|
If you would like your snippets to be expanded using 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 CTRL-J, just change this: >
|
||
|
|
|
||
|
|
ino <tab> <c-r>=TriggerSnippet()<cr>
|
||
|
|
snor <tab> <esc>i<right><c-r>=TriggerSnippet()<cr>
|
||
|
|
|
||
|
|
to this: >
|
||
|
|
ino <c-j> <c-r>=TriggerSnippet()<cr>
|
||
|
|
snor <c-j> <esc>i<right><c-r>=TriggerSnippet()<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] <shift-tab> can now be used to jump tab stops in reverse order.
|
||
|
|
|
||
|
|
==============================================================================
|
||
|
|
DISADVANTAGES *snipMate-disadvantages*
|
||
|
|
|
||
|
|
snipMate.vim currently has the following disadvantages to TextMate's snippets:
|
||
|
|
- 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:
|