configfiles/vim/.vim/doc/supertab.txt

*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|
    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 <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 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<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.

  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<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* (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 '</'.

  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).

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<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: 0)

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 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
(<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.

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>")
    \ 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, "<c-p>") |
    \ 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: