*supertab.txt* Author: Eric Van Dewoestine Original concept and versions up to 0.32 written by Gergely Kontra This plugin is licensed under the terms of the BSD License. Please see supertab.vim for the license in its entirety. ============================================================================== Supertab *supertab* 1. Introduction |supertab-intro| 2. Supertab Usage |supertab-usage| 3. Supertab Options |supertab-options| Default completion type |supertab-defaultcompletion| Secondary default completion type |supertab-contextdefault| Completion contexts |supertab-completioncontexts| Context text |supertab-contexttext| Context Discover |supertab-contextdiscover| Example |supertab-contextexample| Completion Duration |supertab-duration| Preventing Completion After/Before... |supertab-preventcomplete| Changing default mapping |supertab-forwardbackward| Inserting true tabs |supertab-mappingtabliteral| Enhanced longest match support |supertab-longestenhanced| Preselecting the first entry |supertab-longesthighlight| Mapping to end completion |supertab-crmapping| Auto close the preview window |supertab-closepreviewonpopupclose| Keyword completion ignore/match case |supertab-completecase| Completion Chaining |supertab-completionchaining| ============================================================================== 1. Introduction *supertab-intro* Supertab is a plugin which allows you to perform all your insert completion (|ins-completion|) using the tab key. Supertab requires Vim version 7.0 or above. ============================================================================== 2. Supertab usage *supertab-usage* Using Supertab is as easy as hitting or (shift+tab) while in insert mode, with at least one non whitespace character before the cursor, to start the completion and then or again to cycle forwards or backwards through the available completions. Example ('|' denotes the cursor location): bar baz b| Hitting here will start the completion, allowing you to then cycle through the suggested words ('bar' and 'baz'). ============================================================================== 3. Supertab Options *supertab-options* Supertab is configured via several global variables that you can set in your |vimrc| file according to your needs. Below is a comprehensive list of the variables available. Default Completion Type *supertab-defaultcompletion* *g:SuperTabDefaultCompletionType* g:SuperTabDefaultCompletionType (default value: "") Used to set the default completion type. There is no need to escape this value as that will be done for you when the type is set. Example: setting the default completion to 'user' completion: > let g:SuperTabDefaultCompletionType = "" < Note: a special value of 'context' is supported which will result in super tab attempting to use the text preceding the cursor to decide which type of completion to attempt. Currently supertab can recognize method calls or attribute references via '.', '::' or '->', and file path references containing '/'. If the language you are using doesn't use any of the member reference characters listed above, or you'd like to add additional patterns, you can write a custom context function also described in the next section (Completion context). Example: setting the default completion to supertab's 'context' completion: > let g:SuperTabDefaultCompletionType = "context" < /usr/l # will use filename completion myvar.t # will use user completion if completefunc set, # or omni completion if omnifunc set. myvar-> # same as above When using context completion, super tab will fall back to a secondary default completion type set by |g:SuperTabContextDefaultCompletionType|. Note: once the buffer has been initialized, changing the value of this setting will not change the default complete type used. If you want to change the default completion type for the current buffer after it has been set, perhaps in an ftplugin, you'll need to call *SuperTabSetDefaultCompletionType* like so, supplying the completion type you wish to switch to: > call SuperTabSetDefaultCompletionType("") < Secondary default completion type *supertab-contextdefault* *g:SuperTabContextDefaultCompletionType* g:SuperTabContextDefaultCompletionType (default value: "") Sets the default completion type used when g:SuperTabDefaultCompletionType is set to 'context' and no completion type is returned by any of the configured contexts. Note: supertab also supports the b:SuperTabContextDefaultCompletionType variable allowing you to set the default type separately for the current buffer, like from an ftplugin for example. Completion contexts *supertab-completioncontexts* *g:SuperTabCompletionContexts* g:SuperTabCompletionContexts (default value: ['s:ContextText']) Sets the list of contexts used for context completion. This value should be a list of function names which provide the context implementation. When supertab starts context completion, each of these contexts will be consulted, in the order they were supplied, to determine the completion type to use. If a context returns a completion type, that type will be used, otherwise the next context in the list will be consulted. If after executing all the context functions, no completion type has been determined, then the value of |g:SuperTabContextDefaultCompletionType| will be used. Note: supertab also supports the b:SuperTabCompletionContexts variable allowing you to set the list of contexts separately for the current buffer, like from an ftplugin for example. Built in completion contexts: s:ContextText *supertab-contexttext* The text context will examine the text near the cursor to decide which type of completion to attempt. Currently the text context can recognize method calls or attribute references via '.', '::' or '->', and file path references containing '/'. /usr/l # will use filename completion myvar.t # will use user completion if completefunc set, or # omni completion if omnifunc set. myvar-> # same as above Supported configuration attributes: *g:SuperTabContextTextFileTypeExclusions* List of file types for which the text context will be skipped. *g:SuperTabContextTextOmniPrecedence* (default: ['&completefunc', '&omnifunc']) *b:SuperTabContextTextOmniPrecedence* List of omni completion option names in the order of precedence that they should be used if available. By default, user completion will be given precedence over omni completion, but you can use this variable to give omni completion higher precedence by placing it first in the list. *g:SuperTabContextTextMemberPatterns* (default: ['\.', '>\?::', '->']) *b:SuperTabContextTextMemberPatterns* List of patterns used to determine when omni/user completion should be used. The default list consists of the most common patterns used to access module/class/object members. Note: For html and xml based files, the buffer local version of the above two settings are set to trigger omni completion first when encountering a potential end tag pattern of ' let g:SuperTabCompletionContexts = ['s:ContextText', 's:ContextDiscover'] let g:SuperTabContextTextOmniPrecedence = ['&omnifunc', '&completefunc'] let g:SuperTabContextDiscoverDiscovery = \ ["&completefunc:", "&omnifunc:"] < In addition to the default completion contexts, you can plug in your own implementation by creating a globally accessible function that returns the completion type to use (eg. "\\"). > function MyTagContext() if filereadable(expand('%:p:h') . '/tags') return "\\" endif " no return will result in the evaluation of the next " configured context endfunction let g:SuperTabCompletionContexts = \ ['MyTagContext', 's:ContextText', 's:ContextDiscover'] < Here is another example that could be used to add context support for clojure, and perhaps other lisp variants: > let b:SuperTabCompletionContexts = \ ['ClojureContext'] + g:SuperTabCompletionContexts function! ClojureContext() let curline = getline('.') let cnum = col('.') let synname = synIDattr(synID(line('.'), cnum - 1, 1), 'name') if curline =~ '(\S\+\%' . cnum . 'c' && synname !~ '\(String\|Comment\)' return "\\" endif endfunction < Completion Duration *supertab-duration* *g:SuperTabRetainCompletionDuration* g:SuperTabRetainCompletionDuration (default value: 'insert') Determines if, and for how long, the current completion type is retained. The possible values include: 'completion' - The current completion type is only retained for the current completion. Once you have chosen a completion result or exited the completion mode, the default completion type is restored. 'insert' - The current completion type is saved until you exit insert mode (via ESC). Once you exit insert mode the default completion type is restored. (supertab default) 'session' - The current completion type is saved for the duration of your vim session or until you enter a different completion mode. Preventing completion after... *supertab-preventcomplete* *g:SuperTabNoCompleteBefore* *g:SuperTabNoCompleteAfter* g:SuperTabNoCompleteBefore (default value: []) g:SuperTabNoCompleteAfter (default value: ['^', '\s']) These two variables are used to control when supertab will attempt completion or instead fall back to inserting a literal . There are two possible ways to define these variables: 1) by specifying a list of patterns which are tested against the text before and after the current cursor position that when matched, prevent completion. So if you don't want supertab to start completion at the start of a line, after a comma, or after a space, you can set g:SuperTabNoCompleteAfter to ['^', ',', '\s']. 2) by specifying a funcref to a global accessible function which expects as parameter the text to be inspected (before or after) and, based on that (or other factors), it returns 1 if completion must be prevented, 0 otherwise. Note: That a buffer local version of these variables (b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) are also supported should you wish to have different values depending on the file type for instance. Changing the default mapping *supertab-forwardbackward* *g:SuperTabMappingForward* *g:SuperTabMappingBackward* g:SuperTabMappingForward (default value: '') g:SuperTabMappingBackward (default value: '') These two variables allow you to set the keys used to kick off the current completion. By default this is and . To change to something like and , you can add the following to your |vimrc|. > let g:SuperTabMappingForward = '' let g:SuperTabMappingBackward = '' > Note: if the above does not have the desired effect (which may happen in console version of vim), you can try the following mappings. Although the backwards mapping still doesn't seem to work in the console for me, your milage may vary. > let g:SuperTabMappingForward = '' let g:SuperTabMappingBackward = '' < Inserting true tabs *supertab-mappingtabliteral* *g:SuperTabMappingTabLiteral* g:SuperTabMappingTabLiteral (default value: '') Sets the key mapping used to insert a literal tab where supertab would otherwise attempt to kick off insert completion. The default is '' (ctrl-tab) which unfortunately might not work at the console. So if you are using a console vim and want this functionality, you may have to change it to something that is supported. Alternatively, you can escape the with (see |i_CTRL-V| for more infos). See also |supertab-preventcomplete|. Enhanced longest match support *supertab-longestenhanced* *g:SuperTabLongestEnhanced* g:SuperTabLongestEnhanced (default value: 0) When enabled and 'longest' is in your |completeopt| setting, supertab will provide an enhanced longest match support where typing one or more letters and hitting tab again while in a completion mode will complete the longest common match using the new text in the buffer. For example, say you have a buffer with the following contents: FooBarFoo FooBar Foo FooBarBaz And you then type F. Vim's builtin longest support will complete the longest common text 'Foo' and offer 'FooBarFoo', 'FooBar', 'Foo', and 'FooBarBaz' as possible completions. With supertab's longest match enhancement disabled, typing B while still in the completion mode will end up completing 'FooBarBaz' or 'FooBarFoo' depending your settings, instead of the next longest common match of 'FooBar'. With supertab's enhanced longest match feature enabled, the typing of B will result in the next longest text being completed. Preselecting the first entry *supertab-longesthighlight* *g:SuperTabLongestHighlight* g:SuperTabLongestHighlight (default value: 0) Sets whether or not to pre-highlight the first match when completeopt has the popup menu enabled and the 'longest' option as well. When enabled, will kick off completion and pre-select the first entry in the popup menu, allowing you to simply hit to use it. Mapping to end completion *supertab-crmapping* *g:SuperTabCrMapping* g:SuperTabCrMapping (default value: 0) When enabled, will cancel completion mode preserving the current text. Compatibility with other plugins: - endwise: compatible - delimitMate: not compatible (disabled if the delimitMate mapping is detected.) Note: if you have an insert expression mapping with a in it or an insert abbreviation containing a , then supertab will not create a mapping which could potentially cause problems with those. Auto close the preview window *supertab-closepreviewonpopupclose* *g:SuperTabClosePreviewOnPopupClose* g:SuperTabClosePreviewOnPopupClose (default value: 0) When enabled, supertab will attempt to close vim's completion preview window when the completion popup closes (completion is finished or canceled). Completion ignore/match case *supertab-completecase* *g:SuperTabCompleteCase* g:SuperTabCompleteCase (default value: 'inherit') When issuing completions (keyword and potentially others), the value of your |'ignorecase'| setting will determine what results are returned based on whether or not you've chosen to ignore case or not. However, you may have |'ignorecase'| set or unset for other reasons and don't want that value considered when using insert completion. SuperTab allows you temporarily override |'ignorecase'| by setting g:SuperTabCompleteCase to either 'ignore' or 'match' depending on whether you want to always ignore or match case when using insert completion. Note: third party omni/user completion plugins may or may not honor |'ignorecase'|. If they do not, then you can probably contact them to add that support. Completion Chaining *supertab-completionchaining* SuperTab provides the ability to chain one of the completion functions (|completefunc| or |omnifunc|) together with one of the default vim completion key sequences (|ins-completion|), giving you the ability to attempt completion with the first, and upon no results, fall back to the second. To utilize this feature you need to call the *SuperTabChain* function where the first argument is the name of a vim compatible |complete-function| and the second is one of vim's insert completion (|ins-completion|) key bindings (, , , etc). Calling this function will set the current buffer's |completefunc| option to a supertab provided implementation which utilizes the supplied arguments to perform the completion. Here is an example that can be added to your .vimrc which will setup the supertab chaining for any filetype that has a provided |omnifunc| to first try that, then fall back to supertab's default, , completion: > autocmd FileType * \ if &omnifunc != '' | \ call SuperTabChain(&omnifunc, "") | \ endif < You can also specify whether or not the 'context' completion method will be used as part of your completion chaining. If you've already set your default completion type to 'context', then no further action is needed. If however you haven't set that or don't want to use 'context' completion in this case, then you can supply a third argument to SuperTabChain which is a boolean (1 or 0) indicationg whether you want to use 'context' completion (1) or not (0). Here is an example where 'context' is the global default and completion chaining is enabled for file types that have omni completion support: > let g:SuperTabDefaultCompletionType = 'context' autocmd FileType * \ if &omnifunc != '' | \ call SuperTabChain(&omnifunc, "") | \ endif < This configuration will result in a completion flow like so: if text before the cursor looks like a file path: use file completion elif text before the cursor looks like an attempt to access a member (method, field, etc): use user completion where user completion is currently set to supertab's completion chaining, resulting in: if omni completion has results: use omni completion else: use keyword completion else: use keyword completion Note: Completion chaining only supports chaining 1 completion function (omni or user) with 1 regular completion keybinding. All other combinations of completions (2 or more completion functions, 2 or more key bindings, etc.) are not supported due to limitations imposed by vim's code completion implementation. Note: If the |completefunc| or |omnifunc| use vim's |complete_add()| instead of returning completion results as a list, then Supertab's completion chaining won't work properly with it since Supertab uses the function result to determine if it should fallback to the next completion type. vim:tw=78:ts=8:ft=help:norl: