mirror of https://github.com/captn3m0/dotfiles.git
317 lines
13 KiB
Plaintext
317 lines
13 KiB
Plaintext
*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|
|
|
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|
|
|
|
|
==============================================================================
|
|
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 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/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']
|
|
|
|
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.
|
|
|
|
|
|
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>, 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 after a comma or space, you can set
|
|
g:SuperTabNoCompleteAfter to [',', '\s'].
|
|
|
|
Note: That a buffer local version of these variables
|
|
(b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) is 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.
|
|
|
|
|
|
Close the preview window on <cr> *supertab-crclosepreview*
|
|
*g:SuperTabCrClosePreview*
|
|
|
|
g:SuperTabCrClosePreview (default value: 0)
|
|
|
|
When enabled, <cr> will close the completion preview window if open. Note,
|
|
|g:SuperTabCrMapping| must also be enabled.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|