*supertab.txt*
Authors:
Original: Gergely Kontra <kgergely@mcl.hu>
Current: Eric Van Dewoestine <ervandew@gmail.com> (as of version 0.4)
Contributors:
Christophe-Marie Duquesne <chm.duquesne@gmail.com> (documentation)
Please direct all correspondence to Eric.
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|
Midword completion |supertab-midword|
Changing default mapping |supertab-forwardbackward|
Inserting true tabs |supertab-mappingtabliteral|
Preselecting the first entry |supertab-longesthighlight|
==============================================================================
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.
g:SuperTabDefaultCompletionType |supertab-defaultcompletion|
The default completion type to use. If you program in languages that support
omni or user completions, it is highly recommended setting this to
'context'.
For help about built in completion types in vim, see |i_CTRL-X_index|.
g:SuperTabContextDefaultCompletionType |supertab-contextdefault|
The default completion type to use when 'context' is the global default, but
context completion has determined that neither omni, user, or file
completion should be used in the current context.
g:SuperTabCompletionContexts |supertab-completioncontexts|
Used to configure a list of function names which are used when the global
default type is 'context'. These functions will be consulted in order to
determine which completion type to use. Advanced users can plug in their own
functions here to customize their 'context' completion.
g:SuperTabRetainCompletionDuration |supertab-duration|
This setting determines how long a non-default completion type should be
retained as the temporary default. By default supertab will retain the
alternate completion type until you leave insert mode.
g:SuperTabMidWordCompletion |supertab-midword|
This can be used to turn off completion if you are in the middle of a word
(word characters immediately preceding and following the cursor).
g:SuperTabMappingForward |supertab-forwardbackward|
g:SuperTabMappingBackward |supertab-forwardbackward|
If using the tab key for completion isn't for you, then you can use these to
set an alternate key to be used for your insert completion needs.
g:SuperTabMappingTabLiteral |supertab-mappingtabliteral|
For those rare cases where supertab would normal want to start insert
completion, but you just want to insert a tab, this setting is used to
define the key combination to use to do just that. By default Ctrl-Tab is
used.
g:SuperTabLongestHighlight |supertab-longesthighlight|
When enabled and you have the completion popup enable and 'longest' in your
completeopt, supertab will auto highlight the first selection in the popup.
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 super tab can recognize method
calls or attribute references via '.', '::' or '->', and file path
references containing '/'.
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 the default 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.
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