diff options
Diffstat (limited to 'modules/vim/vim.dot.link/doc/snipMate.txt')
| -rw-r--r-- | modules/vim/vim.dot.link/doc/snipMate.txt | 286 |
1 files changed, 0 insertions, 286 deletions
diff --git a/modules/vim/vim.dot.link/doc/snipMate.txt b/modules/vim/vim.dot.link/doc/snipMate.txt deleted file mode 100644 index 704d44a..0000000 --- a/modules/vim/vim.dot.link/doc/snipMate.txt +++ /dev/null @@ -1,286 +0,0 @@ -*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: |