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