443 lines
18 KiB
Plaintext
443 lines
18 KiB
Plaintext
*supertab.txt*
|
|
|
|
Author: Eric Van Dewoestine <ervandew@gmail.com>
|
|
Original concept and versions up to 0.32 written by
|
|
Gergely Kontra <kgergely@mcl.hu>
|
|
|
|
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 <cr> to end completion |supertab-crmapping|
|
|
Auto close the preview window |supertab-closepreviewonpopupclose|
|
|
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 <Tab> or <S-Tab> (shift+tab) while in
|
|
insert mode, with at least one non whitespace character before the cursor, to
|
|
start the completion and then <Tab> or <S-Tab> again to cycle forwards or
|
|
backwards through the available completions.
|
|
|
|
Example ('|' denotes the cursor location):
|
|
|
|
bar
|
|
baz
|
|
b|<Tab> Hitting <Tab> 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: "<c-p>")
|
|
|
|
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 = "<c-x><c-u>"
|
|
<
|
|
|
|
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 aditional patterns,
|
|
you can write a custom conxtext function als decribed in the next section
|
|
(Completion context).
|
|
|
|
Example: setting the default completion to supertab's 'context' completion:
|
|
>
|
|
let g:SuperTabDefaultCompletionType = "context"
|
|
<
|
|
|
|
/usr/l<tab> # will use filename completion
|
|
myvar.t<tab> # will use user completion if completefunc set,
|
|
# or omni completion if omnifunc set.
|
|
myvar-><tab> # 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("<c-x><c-u>")
|
|
<
|
|
|
|
|
|
Secondary default completion type *supertab-contextdefault*
|
|
*g:SuperTabContextDefaultCompletionType*
|
|
|
|
g:SuperTabContextDefaultCompletionType (default value: "<c-p>")
|
|
|
|
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.
|
|
|
|
|
|
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<tab> # will use filename completion
|
|
myvar.t<tab> # will use user completion if completefunc set, or
|
|
# omni completion if omnifunc set.
|
|
myvar-><tab> # same as above
|
|
|
|
Supported configuration attributes:
|
|
|
|
g:SuperTabContextTextFileTypeExclusions
|
|
List of file types for which the text context will be skipped.
|
|
|
|
g: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.
|
|
|
|
s:ContextDiscover *supertab-contextdiscover*
|
|
|
|
This context will use the 'g:SuperTabContextDiscoverDiscovery' variable to
|
|
determine the completion type to use. It will evaluate each value, in the
|
|
order they were defined, until a variable evaluates to a non-zero or
|
|
non-empty value, then the associated completion type is used.
|
|
|
|
Supported configuration properties:
|
|
|
|
g:SuperTabContextDiscoverDiscovery
|
|
List of variable:completionType mappings.
|
|
|
|
Example context configuration: *supertab-contextexample*
|
|
|
|
>
|
|
let g:SuperTabCompletionContexts = ['s:ContextText', 's:ContextDiscover']
|
|
let g:SuperTabContextTextOmniPrecedence = ['&omnifunc', '&completefunc']
|
|
let g:SuperTabContextDiscoverDiscovery =
|
|
\ ["&completefunc:<c-x><c-u>", "&omnifunc:<c-x><c-o>"]
|
|
<
|
|
|
|
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. "\<c-x>\<c-u>").
|
|
|
|
>
|
|
function MyTagContext()
|
|
if filereadable(expand('%:p:h') . '/tags')
|
|
return "\<c-x>\<c-]>"
|
|
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 "\<c-x>\<c-o>"
|
|
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 <tab>. 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: '<tab>')
|
|
g:SuperTabMappingBackward (default value: '<s-tab>')
|
|
|
|
These two variables allow you to set the keys used to kick off the current
|
|
completion. By default this is <tab> and <s-tab>. To change to something
|
|
like <c-space> and <s-c-space>, you can add the following to your |vimrc|.
|
|
|
|
>
|
|
let g:SuperTabMappingForward = '<c-space>'
|
|
let g:SuperTabMappingBackward = '<s-c-space>'
|
|
>
|
|
|
|
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 = '<nul>'
|
|
let g:SuperTabMappingBackward = '<s-nul>'
|
|
<
|
|
|
|
|
|
Inserting true tabs *supertab-mappingtabliteral*
|
|
*g:SuperTabMappingTabLiteral*
|
|
|
|
g:SuperTabMappingTabLiteral (default value: '<c-tab>')
|
|
|
|
Sets the key mapping used to insert a literal tab where supertab would
|
|
otherwise attempt to kick off insert completion. The default is '<c-tab>'
|
|
(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 <tab> with
|
|
<c-v> (see |i_CTRL-V| for more infos).
|
|
|
|
|
|
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<tab>. 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<tab> 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<tab> 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, <tab> will
|
|
kick off completion and pre-select the first entry in the popup menu, allowing
|
|
you to simply hit <enter> to use it.
|
|
|
|
|
|
Mapping <cr> to end completion *supertab-crmapping*
|
|
*g:SuperTabCrMapping*
|
|
|
|
g:SuperTabCrMapping (default value: 1)
|
|
|
|
When enabled, <cr> will cancel completion mode preserving the current text.
|
|
|
|
Compatibility with other plugins:
|
|
- endwise: compatible
|
|
- delimitMate: not compatible (disabled if the delimitMate <cr> mapping is
|
|
detected.)
|
|
|
|
Note: if you have an insert expression mapping with a <cr> in it or an insert
|
|
abbreviation containing a <cr>, then supertab will not create a <cr> 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 Chaining *supertab-completionchaining*
|
|
|
|
SuperTab provides the ability to chain one of the completion functions
|
|
(|completefunc| or |omnifunc|) together with a 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
|
|
(<c-p>, <c-n>, <c-x><c-]>, 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. Since the
|
|
|completefunc| option is being set, this feature must be used with
|
|
|g:SuperTabDefaultCompletionType| set to either "context" or "<c-x><c-u>".
|
|
|
|
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, <c-p>, completion:
|
|
|
|
>
|
|
autocmd FileType *
|
|
\ if &omnifunc != '' |
|
|
\ call SuperTabChain(&omnifunc, "<c-p>") |
|
|
\ call SuperTabSetDefaultCompletionType("<c-x><c-u>") |
|
|
\ endif
|
|
<
|
|
|
|
Notice that this autocmd set's the supertab default completion type to user
|
|
completion. This is because the call to SuperTabChain will set your buffer's
|
|
|'completefunc'| to a supertab defined function which handles the completion
|
|
chaining. If that function is never called, by user completion being invoked
|
|
via supertab, then completion chaining will not execute. As noted above though,
|
|
instead of setting the default to user completion, you can alternatively set
|
|
it supertab's 'context' completion type, in which case supertab's 'context'
|
|
completion mechanism document above will execute first, and when that context
|
|
logic kicks off a user completion, based on the current context, then
|
|
supertab's completion chaining will then take over.
|
|
|
|
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, "<c-p>") |
|
|
\ endif
|
|
<
|
|
|
|
That 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:
|