*snippets_emu.txt* For Vim version 7.0. Last change: 2006 Dec 26 VIM REFERENCE MANUAL by Panos Laganakos and Felix Ingram 1. SnippetsEmu Features |snippets_emu-features| Basic Snippets |basic-snippet| Named Tags |named-tags| Tag Commands |snippet-commands| Buffer Specific Snippets |snip-buffer-specific| Filetype Specific Snippets |snip-ftplugin| Snippets menu |snip-menu| 2. SnippetsEmu Options |snippets_emu-options| Start and End Tags |snip-start-end-tags| Element Delimiter |snip-start-end-tags| Remapping the default jump key |snip-remap-key| 3. Detailed Explanations |snip-detailed-explanations| Valid Tag Names |snip-tag-name-syntax| Advanced Tag Command Examples |snip-advanced-tag-commands| 4. SnippetsEmu Contact Details |snip-contact-details| 5. Contributors |snip-contributors| 6. SnippetsEmu Known Bugs |snippets_emu-bugs| 7. Troubleshooting |snippets_emu-troubleshooting| {Vi does not have any of these features} ============================================================================== SNIPPETSEMU FEATURES *snippets_emu-features* SnippetsEmu attempts to emulate several of the snippets features of the OS X editor TextMate, in particular the variable bouncing and replacement behaviour. Simple usage is built up around the following functionality: Basic Snippet |basic-snippet| Named Tags |named-tags| Executable Snippet |snippet-commands| Buffer Specific Snippets |snip-buffer-specific| *basic-snippet* *:Snippet* Basic Snippet ~ A basic snippet can save you a lot of typing. Define a word trigger and on insertion it will be expanded to the full snippet. SnippetsEmu allows the user to define markers within the larger piece of text which will be used to place the cursor upon expansion. The command used to define a snippet is 'Snippet'. Basic Syntax: > :Snippet trigger_name The cursor will be placed here: <{}> Trailing text In insert mode typing 'trigger_name' will remove 'trigger_name' and replace it with the text: 'The cursor will be placed here: Trailing text'. The cursor will be placed between the two spaces before the word 'Trailing' NOTE: All text should be entered on the same command line. The formatting of this document may mean that examples are wrapped but they should all be entered on a single line. *named-tags* Named tags ~ Instead of the simple '<{}>' tags used for cursor placement a user can define named tags. When the value of a named tag is changed then all other tags with that name will be changed to the same value. E.g. > :Snippet trigger My name is <{forename}> <{surname}>. Call me <{forename}>. In insert mode typing 'trigger' will place the cursor inside the '<{forename}>' tag. Whatever is entered inside the tag will replace the other similarly named tag at the end of the line after the user presses 'Tab'. If no value is entered for a named tag then the tag's name will be used instead. This is one way of defining default values. Using the above example, entering 'trigger' and pressing 'Tab' twice will result in the following text: > My name is forename surname. Please call me forename. The rules for what constitutes a valid tag name are explained below. See |snip-tag-name-syntax|. *snippet-commands* Tag commands ~ Tags can contain commands. Commands can be any Vim function, including user defined functions. A common example is performing substitutions. E.g. > :Snippet trigger My name is <{name}>. I SAID: MY NAME IS <{name:substitute(@z,'.','\u&','g')}>! The value entered in the <{name}> tag will be passed to the command in the second <{name}> tag in the @z register (any value already in @z will be preserved and restored). The substitute command will change the entered value to be in upper case. I.e. Entering 'trigger' and typing 'Tycho' will result in the following text: > My name is Tycho. I SAID: MY NAME IS TYCHO! ~ *snip-special-vars* There is a set of special variables which can be included in snippets. These will be replaced before the snippet's text is inserted into the buffer. The list of available variables is detailed below: * SNIP_FILE_NAME - The current file name (from 'expand("%")') * SNIP_ISO_DATE - The current date in YYYY-MM-DD format. *snip-snippet-commands* In addition to tag commands it is also possible to define commands which will be executed before the snippet is inserted into the buffer. These are defined within double backticks. E.g. > :Snippet date The current date is ``strftime("%c")`` Commands are standard Vim commands and will be 'exec'uted and the command output substituted into the text. *snip-buffer-specific* Buffer Specific Snippets ~ The Snippet command defines buffer specific snippets. This is the recommended option when using filetype specific snippets. It is possible to define 'global' snippets which will act across all buffers. These can be defined using the legacy 'Iabbr' command (note the capital 'I'). E.g. > Iabbr for for <{var}> in <{list}>:<{}> ~ *snip-ftplugin* The preferred practice for defining filetype specific snippets is to include them in files named _snippets.vim and for these files to be placed in the ~/.vim/after/ftplugin directory (or vimfiles\after\ftplugin under Windows). When a file of a specific type is loaded so will all of the defined snippets. The 'after' directory is used to ensure that the plugin has been loaded. It is also recommended that the following is included at the top of the file: > if !exists('loaded_snippet') || &cp finish endif This will stop errors being generated if the plugin has not loaded for any reason. Users wishing to add their own filetype snippets should add them to a separate file to ensure they are not lost when upgrading the plugin. Naming the files _mysnippets.vim or similar is the preferred practice. *snip-menu* When loading the plugin will search for all files named '*_snippets.vim'. These will be added to the 'Snippets' menu which is available in Normal mode. Selecting options from the menu will source the file and hence load any snippets defined within it. *creating-snippets* *CreateSnippet* [range]CreateSnippet The CreateSnippet command allows the simple creation of snippets for use within your own file. Without a range the current line will be used. When passed a range then all the lines in the range will be converted for use in a command. Snippets created by the command will be added to a scratch buffer called 'Snippets'. The current value of an empty tag (snip_start_tag.snip_end_tag, '<{}>' by default) will be added to the unnamed register and so can be inserted with appropriate paste commands. *CreateBundleSnippet* [range]CreateBundleSnippet CreateBundleSnippet works exactly like CreateSnippet but the resulting text will be suitable for including in one of the included bundles. The unnamed register will include the text '"st.et."' so start and end tag agnostic empty tags can be included. =============================================================================== SNIPPETSEMU OPTIONS *snippets_emu-options* *snip-start-end-tags* Start and End Tags ~ By default the start and end tags are set to be '<{' and '}>'. These can be changed by setting the following variables in vimrc: > g:snip_start_tag g:snip_end_tag They can be also changed for a specific buffer by setting the following: > b:snip_start_tag b:snip_end_tag ~ *snip-elem-delimiter* Element Delimiter ~ The value of snip_elem_delim is used to separate a tag's name and its command. By default it is set to ':' but can be set as above either globally or for a specific buffer using the following variables: > g:snip_elem_delim b:snip_elem_delim ~ *snip-remap-key* Remapping the default jump key ~ The trigger key is mapped to Tab by default. Some people may wish to remap this if it causes conflicts with other plugins. The key can be set in your <.vimrc> by setting the 'g:snippetsEmu_key' variable. An example > let g:snippetsEmu_key = "" Snippets will now be triggered by Shift-Tab rather than just Tab. NB, this example may not work in all terminals as some trap Shift-Tab before it gets to Vim. ~ ============================================================================== DETAILED EXPLANATIONS *snip-detailed-explanations* *snip-tag-name-syntax* Valid Tag Names ~ Tag names cannot contain whitespace unless they are enclosed in quotes. Valid Examples: > <{validName}> <{"valid name"}> <{tagName:command}> <{"Tag Name":command}> Invalid Examples: > <{invalid name}> <{Tag Name:command}> <{:command}> ~ *snip-advanced-tag-commands* Advanced Tag Command Examples ~ Commands in tags can be as complex as desired. Readability is the main limitation as the command will be placed in the document before execution. The preferred method for defining complex commands is to hide the functionality in a user function. Example: > function! Count(haystack, needle) let counter = 0 let index = match(a:haystack, a:needle) while index > -1 let counter = counter + 1 let index = match(a:haystack, a:needle, index+1) endwhile return counter endfunction function! PyArgList(count) if a:count == 0 return "(,)" else return '('.repeat('<{}>, ', a:count).')' endif endfunction Snippet pf print "<{s}>" % <{s:PyArgList(Count(@z, '%[^%]'))}><{}> The above snippet will expand 'pf' to 'print "<{s}>" ...'. The user then enters a format string. Once the string is entered the Count and PyArgList functions are used to generate a number of empty tags. *snip-limitations* The above represents once of the limitations of the plugin. Due to the way tags are identified it is not possible to include empty tags in another tag's command. The only way to generate empty tags is to return them from a function as in the above example. For other examples see the included bundles. *snip-bundles* The included bundles are not defined in the 'preferred style'. In order to accommodate users who wish to redefine the default tags all snippet definitions are 'executed' with the 'exec' command. E.g. > exec "Snippet test This isn't the right way to ".st.et." define snippets" Executing the command allows 'st' and 'et' to be used in place of start and end tags. 'st' and 'et' are defined elsewhere in the bundle file. ============================================================================== SNIPPETSEMU CONTACT DETAILS *snip-contact-details* To contact the author please email: F Ingram lists gmail com The author welcomes corrections to this documentation, example snippets and bug reports. The plugin is also currently hosted at Google Code: http://code.google.com/p/snippetsemu Bug reports can also be posted on the hosting site: http://code.google.com/p/snippetsemu/issues/list *snip-contributors* Contributors to SnippetsEmu ~ Patches: Ori Avtalion - Improvements to Snippet command Freddy Vulto - Improved behaviour Andy Block - Bug with commands on same line. This is why I should do better test suites. bzklrm - Removal of some normal commands Priit Tamboom - Sorting out left and right mappings Documentation: Panos Laganakos - Greek translation (coming soon) Bundles: Panos Laganakos - Python snippets Alex Pounds - Django snippets Chris Lasher - Python snippets knipknap - Python snippets James Widman - C snippets ============================================================================== SNIPPETSEMU KNOWN BUGS *snippets_emu-bugs* Bugs are currently tracked on Google Code. Please post any you find on the issue tracker: http://code.google.com/p/snippetsemu/issues/list ============================================================================== SNIPPETSEMU TROUBLESHOOTING *snippets_emu-troubleshooting* Problem: Bundles are not loading. Answer: Ensure that you have filetype plugins turned on. Include the following in your vimrc: > filetype plugin on vim:tw=78:sw=4:ts=8:ft=help:norl: