diff options
Diffstat (limited to 'vim/doc/snippets_emu.txt')
| -rw-r--r-- | vim/doc/snippets_emu.txt | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/vim/doc/snippets_emu.txt b/vim/doc/snippets_emu.txt new file mode 100644 index 0000000..3644e42 --- /dev/null +++ b/vim/doc/snippets_emu.txt @@ -0,0 +1,354 @@ +*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<Tab>' 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<Tab>' 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<Tab>' 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<Tab>' and typing 'Tycho<Tab>' +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}>:<CR><{}> +~ + *snip-ftplugin* +The preferred practice for defining filetype specific snippets is to include +them in files named <filetype>_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 +<filetype>_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 = "<S-Tab>" + +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, '%[^%]'))}><CR><{}> + +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 <dot> Ingram <dot> lists <at> gmail <dot> 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: |