« back to all changes in this revision
Viewing changes to vim/.vim/doc/snipMate.txt
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Viktor Nagy
- Date: 2009-09-14 11:59:06 UTC
- Revision ID: viktor.nagy@gmail.com-20090914115906-t5ahg2oj4p4wtjpp
Initial commit
* public ssh key
* some short scripts
* vim configuration
* public ssh key
* some short scripts
* vim configuration
- files added:
- .ssh
- bin
- vim
- vim/.vim
- vim/.vim/after
- vim/.vim/after/plugin
- vim/.vim/autoload
- vim/.vim/doc
- vim/.vim/ftplugin
- vim/.vim/ftplugin/xml.vim
- vim/.vim/plugin
- vim/.vim/snippets
- vim/.vim/snippets/django.snippets
- vim/.vim/snippets/django_template.snippets
- vim/.vim/syntax
added
removed
vim/.vim/doc/snipMate.txt
1
*snipMate.txt* Plugin for using TextMate-style snippets in Vim.
2
3
snipMate *snippet* *snippets* *snipMate*
4
Last Change: July 13, 2009
5
6
|snipMate-description| Description
7
|snipMate-syntax| Snippet syntax
8
|snipMate-usage| Usage
9
|snipMate-settings| Settings
10
|snipMate-features| Features
11
|snipMate-disadvantages| Disadvantages to TextMate
12
|snipMate-contact| Contact
13
14
For Vim version 7.0 or later.
15
This plugin only works if 'compatible' is not set.
16
{Vi does not have any of these features.}
17
18
==============================================================================
19
DESCRIPTION *snipMate-description*
20
21
snipMate.vim implements some of TextMate's snippets features in Vim. A
22
snippet is a piece of often-typed text that you can insert into your
23
document using a trigger word followed by a <tab>.
24
25
For instance, in a C file using the default installation of snipMate.vim, if
26
you type "for<tab>" in insert mode, it will expand a typical for loop in C: >
27
28
for (i = 0; i < count; i++) {
29
30
}
31
32
33
To go to the next item in the loop, simply <tab> over to it; if there is
34
repeated code, such as the "i" variable in this example, you can simply
35
start typing once it's highlighted and all the matches specified in the
36
snippet will be updated. To go in reverse, use <shift-tab>.
37
38
==============================================================================
39
SYNTAX *snippet-syntax*
40
41
Snippets can be defined in two ways. They can be in their own file, named
42
after their trigger in 'snippets/<filetype>/<trigger>.snippet', or they can be
43
defined together in a 'snippets/<filetype>.snippets' file. Note that dotted
44
'filetype' syntax is supported -- e.g., you can use >
45
46
:set ft=html.eruby
47
48
to activate snippets for both HTML and eRuby for the current file.
49
50
The syntax for snippets in *.snippets files is the following: >
51
52
snippet trigger
53
expanded text
54
more expanded text
55
56
Note that the first hard tab after the snippet trigger is required, and not
57
expanded in the actual snippet. The syntax for *.snippet files is the same,
58
only without the trigger declaration and starting indentation.
59
60
Also note that snippets must be defined using hard tabs. They can be expanded
61
to spaces later if desired (see |snipMate-indenting|).
62
63
"#" is used as a line-comment character in *.snippets files; however, they can
64
only be used outside of a snippet declaration. E.g.: >
65
66
# this is a correct comment
67
snippet trigger
68
expanded text
69
snippet another_trigger
70
# this isn't a comment!
71
expanded text
72
<
73
This should hopefully be obvious with the included syntax highlighting.
74
75
*snipMate-${#}*
76
Tab stops ~
77
78
By default, the cursor is placed at the end of a snippet. To specify where the
79
cursor is to be placed next, use "${#}", where the # is the number of the tab
80
stop. E.g., to place the cursor first on the id of a <div> tag, and then allow
81
the user to press <tab> to go to the middle of it:
82
>
83
snippet div
84
<div id="${1}">
85
${2}
86
</div>
87
<
88
*snipMate-placeholders* *snipMate-${#:}* *snipMate-$#*
89
Placeholders ~
90
91
Placeholder text can be supplied using "${#:text}", where # is the number of
92
the tab stop. This text then can be copied throughout the snippet using "$#",
93
given # is the same number as used before. So, to make a C for loop: >
94
95
snippet for
96
for (${2:i}; $2 < ${1:count}; $1++) {
97
${4}
98
}
99
100
This will cause "count" to first be selected and change if the user starts
101
typing. When <tab> is pressed, the "i" in ${2}'s position will be selected;
102
all $2 variables will default to "i" and automatically be updated if the user
103
starts typing.
104
NOTE: "$#" syntax is used only for variables, not for tab stops as in TextMate.
105
106
Variables within variables are also possible. For instance: >
107
108
snippet opt
109
<option value="${1:option}">${2:$1}</option>
110
111
Will, as usual, cause "option" to first be selected and update all the $1
112
variables if the user starts typing. Since one of these variables is inside of
113
${2}, this text will then be used as a placeholder for the next tab stop,
114
allowing the user to change it if he wishes.
115
116
To copy a value throughout a snippet without supplying default text, simply
117
use the "${#:}" construct without the text; e.g.: >
118
119
snippet foo
120
${1:}bar$1
121
< *snipMate-commands*
122
Interpolated Vim Script ~
123
124
Snippets can also contain Vim script commands that are executed (via |eval()|)
125
when the snippet is inserted. Commands are given inside backticks (`...`); for
126
TextMates's functionality, use the |system()| function. E.g.: >
127
128
snippet date
129
`system("date +%Y-%m-%d")`
130
131
will insert the current date, assuming you are on a Unix system. Note that you
132
can also (and should) use |strftime()| for this example.
133
134
Filename([{expr}] [, {defaultText}]) *snipMate-filename* *Filename()*
135
136
Since the current filename is used often in snippets, a default function
137
has been defined for it in snipMate.vim, appropriately called Filename().
138
139
With no arguments, the default filename without an extension is returned;
140
the first argument specifies what to place before or after the filename,
141
and the second argument supplies the default text to be used if the file
142
has not been named. "$1" in the first argument is replaced with the filename;
143
if you only want the filename to be returned, the first argument can be left
144
blank. Examples: >
145
146
snippet filename
147
`Filename()`
148
snippet filename_with_default
149
`Filename('', 'name')`
150
snippet filename_foo
151
`filename('$1_foo')`
152
153
The first example returns the filename if it the file has been named, and an
154
empty string if it hasn't. The second returns the filename if it's been named,
155
and "name" if it hasn't. The third returns the filename followed by "_foo" if
156
it has been named, and an empty string if it hasn't.
157
158
*multi_snip*
159
To specify that a snippet can have multiple matches in a *.snippets file, use
160
this syntax: >
161
162
snippet trigger A description of snippet #1
163
expand this text
164
snippet trigger A description of snippet #2
165
expand THIS text!
166
167
In this example, when "trigger<tab>" is typed, a numbered menu containing all
168
of the descriptions of the "trigger" will be shown; when the user presses the
169
corresponding number, that snippet will then be expanded.
170
171
To create a snippet with multiple matches using *.snippet files,
172
simply place all the snippets in a subdirectory with the trigger name:
173
'snippets/<filetype>/<trigger>/<name>.snippet'.
174
175
==============================================================================
176
USAGE *snipMate-usage*
177
178
*'snippets'* *g:snippets_dir*
179
Snippets are by default looked for any 'snippets' directory in your
180
'runtimepath'. Typically, it is located at '~/.vim/snippets/' on *nix or
181
'$HOME\vimfiles\snippets\' on Windows. To change that location or add another
182
one, change the g:snippets_dir variable in your |.vimrc| to your preferred
183
directory, or use the |ExtractSnips()|function. This will be used by the
184
|globpath()| function, and so accepts the same syntax as it (e.g.,
185
comma-separated paths).
186
187
ExtractSnipsFile({directory}, {filetype}) *ExtractSnipsFile()* *.snippets*
188
189
ExtractSnipsFile() extracts the specified *.snippets file for the given
190
filetype. A .snippets file contains multiple snippet declarations for the
191
filetype. It is further explained above, in |snippet-syntax|.
192
193
ExtractSnips({directory}, {filetype}) *ExtractSnips()* *.snippet*
194
195
ExtractSnips() extracts *.snippet files from the specified directory and
196
defines them as snippets for the given filetype. The directory tree should
197
look like this: 'snippets/<filetype>/<trigger>.snippet'. If the snippet has
198
multiple matches, it should look like this:
199
'snippets/<filetype>/<trigger>/<name>.snippet' (see |multi_snip|).
200
201
*ResetSnippets()*
202
The ResetSnippets() function removes all snippets from memory. This is useful
203
to put at the top of a snippet setup file for if you would like to |:source|
204
it multiple times.
205
206
*list-snippets* *i_CTRL-R_<Tab>*
207
If you would like to see what snippets are available, simply type <c-r><tab>
208
in the current buffer to show a list via |popupmenu-completion|.
209
210
==============================================================================
211
SETTINGS *snipMate-settings* *g:snips_author*
212
213
The g:snips_author string (similar to $TM_FULLNAME in TextMate) should be set
214
to your name; it can then be used in snippets to automatically add it. E.g.: >
215
216
let g:snips_author = 'Hubert Farnsworth'
217
snippet name
218
`g:snips_author`
219
<
220
*snipMate-expandtab* *snipMate-indenting*
221
If you would like your snippets to be expanded using spaces instead of tabs,
222
just enable 'expandtab' and set 'softtabstop' to your preferred amount of
223
spaces. If 'softtabstop' is not set, 'shiftwidth' is used instead.
224
225
*snipMate-remap*
226
snipMate does not come with a setting to customize the trigger key, but you
227
can remap it easily in the two lines it's defined in the 'after' directory
228
under 'plugin/snipMate.vim'. For instance, to change the trigger key
229
to CTRL-J, just change this: >
230
231
ino <tab> <c-r>=TriggerSnippet()<cr>
232
snor <tab> <esc>i<right><c-r>=TriggerSnippet()<cr>
233
234
to this: >
235
ino <c-j> <c-r>=TriggerSnippet()<cr>
236
snor <c-j> <esc>i<right><c-r>=TriggerSnippet()<cr>
237
238
==============================================================================
239
FEATURES *snipMate-features*
240
241
snipMate.vim has the following features among others:
242
- The syntax of snippets is very similar to TextMate's, allowing
243
easy conversion.
244
- The position of the snippet is kept transparently (i.e. it does not use
245
markers/placeholders written to the buffer), which allows you to escape
246
out of an incomplete snippet, something particularly useful in Vim.
247
- Variables in snippets are updated as-you-type.
248
- Snippets can have multiple matches.
249
- Snippets can be out of order. For instance, in a do...while loop, the
250
condition can be added before the code.
251
- [New] File-based snippets are supported.
252
- [New] Triggers after non-word delimiters are expanded, e.g. "foo"
253
in "bar.foo".
254
- [New] <shift-tab> can now be used to jump tab stops in reverse order.
255
256
==============================================================================
257
DISADVANTAGES *snipMate-disadvantages*
258
259
snipMate.vim currently has the following disadvantages to TextMate's snippets:
260
- There is no $0; the order of tab stops must be explicitly stated.
261
- Placeholders within placeholders are not possible. E.g.: >
262
263
'<div${1: id="${2:some_id}}">${3}</div>'
264
<
265
In TextMate this would first highlight ' id="some_id"', and if
266
you hit delete it would automatically skip ${2} and go to ${3}
267
on the next <tab>, but if you didn't delete it it would highlight
268
"some_id" first. You cannot do this in snipMate.vim.
269
- Regex cannot be performed on variables, such as "${1/.*/\U&}"
270
- Placeholders cannot span multiple lines.
271
- Activating snippets in different scopes of the same file is
272
not possible.
273
274
Perhaps some of these features will be added in a later release.
275
276
==============================================================================
277
CONTACT *snipMate-contact* *snipMate-author*
278
279
To contact the author (Michael Sanders), please email:
280
msanders42+snipmate <at> gmail <dot> com
281
282
I greatly appreciate any suggestions or improvements offered for the script.
283
284
==============================================================================
285
286
vim:tw=78:ts=8:ft=help:norl:
Loggerhead is a web-based interface for Breezy
Version: 2.0.1