git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/supertab.txt

   1 *supertab.txt*
   2
   3 Authors:
   4   Original: Gergely Kontra <kgergely@mcl.hu>
   5   Current:  Eric Van Dewoestine <ervandew@gmail.com> (as of version 0.4)
   6
   7 Contributors:
   8   Christophe-Marie Duquesne <chm.duquesne@gmail.com> (documentation)
   9
  10 Please direct all correspondence to Eric.
  11
  12 This plugin is licensed under the terms of the BSD License.  Please see
  13 supertab.vim for the license in its entirety.
  14
  15 ==============================================================================
  16 Supertab                                    *supertab*
  17
  18 1. Introduction                             |supertab-intro|
  19 2. Supertab Usage                           |supertab-usage|
  20 3. Supertab Options                         |supertab-options|
  21     Default completion type                 |supertab-defaultcompletion|
  22     Secondary default completion type       |supertab-contextdefault|
  23     Completion contexts                     |supertab-completioncontexts|
  24         Context text                        |supertab-contexttext|
  25         Context Discover                    |supertab-contextdiscover|
  26         Example                             |supertab-contextexample|
  27     Completion Duration                     |supertab-duration|
  28     Preventing Completion After/Before...   |supertab-preventcomplete|
  29     Changing default mapping                |supertab-forwardbackward|
  30     Inserting true tabs                     |supertab-mappingtabliteral|
  31     Enhanced longest match support          |supertab-longestenhanced|
  32     Preselecting the first entry            |supertab-longesthighlight|
  33
  34 ==============================================================================
  35 1. Introduction                             *supertab-intro*
  36
  37 Supertab is a plugin which allows you to perform all your insert completion
  38 (|ins-completion|) using the tab key.
  39
  40 Supertab requires Vim version 7.0 or above.
  41
  42 ==============================================================================
  43 2. Supertab usage                           *supertab-usage*
  44
  45 Using Supertab is as easy as hitting <Tab> or <S-Tab> (shift+tab) while in
  46 insert mode, with at least one non whitespace character before the cursor, to
  47 start the completion and then <Tab> or <S-Tab> again to cycle forwards or
  48 backwards through the available completions.
  49
  50 Example ('|' denotes the cursor location):
  51
  52 bar
  53 baz
  54 b|<Tab>    Hitting <Tab> here will start the completion, allowing you to
  55            then cycle through the suggested words ('bar' and 'baz').
  56
  57 ==============================================================================
  58 3. Supertab Options                         *supertab-options*
  59
  60 Supertab is configured via several global variables that you can set in your
  61 |vimrc| file according to your needs. Below is a comprehensive list of
  62 the variables available.
  63
  64
  65 Default Completion Type             *supertab-defaultcompletion*
  66                                     *g:SuperTabDefaultCompletionType*
  67
  68 g:SuperTabDefaultCompletionType (default value: "<c-p>")
  69
  70 Used to set the default completion type. There is no need to escape this
  71 value as that will be done for you when the type is set.
  72
  73   Example: setting the default completion to 'user' completion:
  74
  75     let g:SuperTabDefaultCompletionType = "<c-x><c-u>"
  76
  77 Note: a special value of 'context' is supported which will result in
  78 super tab attempting to use the text preceding the cursor to decide which
  79 type of completion to attempt.  Currently super tab can recognize method
  80 calls or attribute references via '.', '::' or '->', and file path
  81 references containing '/'.
  82
  83     let g:SuperTabDefaultCompletionType = "context"
  84
  85     /usr/l<tab>     # will use filename completion
  86     myvar.t<tab>    # will use user completion if completefunc set,
  87                     # or omni completion if omnifunc set.
  88     myvar-><tab>    # same as above
  89
  90 When using context completion, super tab will fall back to a secondary default
  91 completion type set by |g:SuperTabContextDefaultCompletionType|.
  92
  93 Note: once the buffer has been initialized, changing the value of this setting
  94 will not change the default complete type used.  If you want to change the
  95 default completion type for the current buffer after it has been set, perhaps
  96 in an ftplugin, you'll need to call SuperTabSetDefaultCompletionType like so,
  97 supplying the completion type you wish to switch to:
  98
  99     call SuperTabSetDefaultCompletionType("<c-x><c-u>")
 100
 101
 102 Secondary default completion type   *supertab-contextdefault*
 103                                     *g:SuperTabContextDefaultCompletionType*
 104
 105 g:SuperTabContextDefaultCompletionType (default value: "<c-p>")
 106
 107 Sets the default completion type used when g:SuperTabDefaultCompletionType is
 108 set to 'context' and no completion type is returned by any of the configured
 109 contexts.
 110
 111
 112 Completion contexts                 *supertab-completioncontexts*
 113                                     *g:SuperTabCompletionContexts*
 114
 115 g:SuperTabCompletionContexts (default value: ['s:ContextText'])
 116
 117 Sets the list of contexts used for context completion.  This value should
 118 be a list of function names which provide the context implementation.
 119
 120 When supertab starts the default completion, each of these contexts will be
 121 consulted, in the order they were supplied, to determine the completion type
 122 to use.  If a context returns a completion type, that type will be used,
 123 otherwise the next context in the list will be consulted.  If after executing
 124 all the context functions, no completion type has been determined, then the
 125 value of g:SuperTabContextDefaultCompletionType will be used.
 126
 127 Built in completion contexts:
 128
 129   s:ContextText                     *supertab-contexttext*
 130
 131   The text context will examine the text near the cursor to decide which type
 132   of completion to attempt.  Currently the text context can recognize method
 133   calls or attribute references via '.', '::' or '->', and file path
 134   references containing '/'.
 135
 136       /usr/l<tab>  # will use filename completion
 137       myvar.t<tab> # will use user completion if completefunc set, or
 138                    # omni completion if omnifunc set.
 139       myvar-><tab> # same as above
 140
 141   Supported configuration attributes:
 142
 143     g:SuperTabContextTextFileTypeExclusions
 144     List of file types for which the text context will be skipped.
 145
 146     g:SuperTabContextTextOmniPrecedence
 147     List of omni completion option names in the order of precedence that they
 148     should be used if available. By default, user completion will be given
 149     precedence over omni completion, but you can use this variable to give
 150     omni completion higher precedence by placing it first in the list.
 151
 152   s:ContextDiscover                 *supertab-contextdiscover*
 153
 154   This context will use the 'g:SuperTabContextDiscoverDiscovery' variable to
 155   determine the completion type to use.  It will evaluate each value, in the
 156   order they were defined, until a variable evaluates to a non-zero or
 157   non-empty value, then the associated completion type is used.
 158
 159   Supported configuration properties:
 160
 161     g:SuperTabContextDiscoverDiscovery
 162     List of variable:completionType mappings.
 163
 164   Example context configuration:    *supertab-contextexample*
 165
 166     let g:SuperTabCompletionContexts = ['s:ContextText', 's:ContextDiscover']
 167     let g:SuperTabContextTextOmniPrecedence = ['&omnifunc', '&completefunc']
 168     let g:SuperTabContextDiscoverDiscovery =
 169         \ ["&completefunc:<c-x><c-u>", "&omnifunc:<c-x><c-o>"]
 170
 171   In addition to the default completion contexts, you can plug in your own
 172   implementation by creating a globally accessible function that returns
 173   the completion type to use (eg. "\<c-x>\<c-u>").
 174
 175     function MyTagContext()
 176       if filereadable(expand('%:p:h') . '/tags')
 177         return "\<c-x>\<c-]>"
 178       endif
 179       " no return will result in the evaluation of the next
 180       " configured context
 181     endfunction
 182     let g:SuperTabCompletionContexts =
 183         \ ['MyTagContext', 's:ContextText', 's:ContextDiscover']
 184
 185   Note: supertab also supports the b:SuperTabCompletionContexts variable
 186   allowing you to set the list of contexts separately for the current buffer,
 187   like from an ftplugin for example.
 188
 189
 190 Completion Duration                 *supertab-duration*
 191                                     *g:SuperTabRetainCompletionDuration*
 192
 193 g:SuperTabRetainCompletionDuration (default value: 'insert')
 194
 195 Determines if, and for how long, the current completion type is retained.
 196 The possible values include:
 197 'completion' - The current completion type is only retained for the
 198                current completion.  Once you have chosen a completion
 199                result or exited the completion mode, the default
 200                completion type is restored.
 201 'insert'     - The current completion type is saved until you exit insert
 202                mode (via ESC).  Once you exit insert mode the default
 203                completion type is restored. (supertab default)
 204 'session'    - The current completion type is saved for the duration of
 205                your vim session or until you enter a different completion
 206                mode.
 207
 208
 209 Preventing completion after...      *supertab-preventcomplete*
 210                                     *g:SuperTabNoCompleteBefore*
 211                                     *g:SuperTabNoCompleteAfter*
 212
 213 g:SuperTabNoCompleteBefore (default value: [])
 214 g:SuperTabNoCompleteAfter (default value: ['\s'])
 215
 216 These two variables are used to control when supertab will attempt completion
 217 or instead fall back to inserting a literal <tab>, by specifying a list of
 218 patterns which are tested against the text before and after the current cursor
 219 position that when matched, prevent completion. So if you don't want supertab
 220 to start completion after a comma or space, you can set
 221 g:SuperTabNoCompleteAfter to [',', '\s'].
 222
 223 Note: That a buffer local version of these variables
 224 (b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) is also supported
 225 should you wish to have different values depending on the file type for
 226 instance.
 227
 228 Changing the default mapping        *supertab-forwardbackward*
 229                                     *g:SuperTabMappingForward*
 230                                     *g:SuperTabMappingBackward*
 231
 232 g:SuperTabMappingForward  (default value: '<tab>')
 233 g:SuperTabMappingBackward (default value: '<s-tab>')
 234
 235 These two variables allow you to set the keys used to kick off the current
 236 completion.  By default this is <tab> and <s-tab>.  To change to something
 237 like <c-space> and <s-c-space>, you can add the following to your |vimrc|.
 238
 239         let g:SuperTabMappingForward = '<c-space>'
 240         let g:SuperTabMappingBackward = '<s-c-space>'
 241
 242 Note: if the above does not have the desired effect (which may happen in
 243 console version of vim), you can try the following mappings.  Although the
 244 backwards mapping still doesn't seem to work in the console for me, your
 245 milage may vary.
 246
 247         let g:SuperTabMappingForward = '<nul>'
 248         let g:SuperTabMappingBackward = '<s-nul>'
 249
 250
 251 Inserting true tabs                 *supertab-mappingtabliteral*
 252                                     *g:SuperTabMappingTabLiteral*
 253
 254 g:SuperTabMappingTabLiteral (default value: '<c-tab>')
 255
 256 Sets the key mapping used to insert a literal tab where supertab would
 257 otherwise attempt to kick off insert completion. The default is '<c-tab>'
 258 (ctrl-tab) which unfortunately might not work at the console. So if you are
 259 using a console vim and want this functionality, you may have to change it to
 260 something that is supported.  Alternatively, you can escape the <tab> with
 261 <c-v> (see |i_CTRL-V| for more infos).
 262
 263
 264 Enhanced longest match support      *supertab-longestenhanced*
 265                                     *g:SuperTabLongestEnhanced*
 266
 267 g:SuperTabLongestEnhanced (default value: 0)
 268
 269 When enabled and 'longest' is in your |completeopt| setting, supertab will
 270 provide an enhanced longest match support where typing one or more letters and
 271 hitting tab again while in a completion mode will complete the longest common
 272 match using the new text in the buffer.
 273
 274 For example, say you have a buffer with the following contents:
 275   FooBarFoo
 276   FooBar
 277   Foo
 278   FooBarBaz
 279 And you then type F<tab>.  Vim's builtin longest support will complete the
 280 longest common text 'Foo' and offer 'FooBarFoo', 'FooBar', 'Foo', and
 281 'FooBarBaz' as possible completions.  With supertab's longest match
 282 enhancement disabled, typing B<tab> while still in the completion mode will
 283 end up completing 'FooBarBaz' or 'FooBarFoo' depending your settings, instead
 284 of the next longest common match of 'FooBar'.  With supertab's enhanced
 285 longest match feature enabled, the typing of B<tab> will result in the next
 286 longest text being completed.
 287
 288
 289 Preselecting the first entry        *supertab-longesthighlight*
 290                                     *g:SuperTabLongestHighlight*
 291
 292 g:SuperTabLongestHighlight (default value: 0)
 293
 294 Sets whether or not to pre-highlight the first match when completeopt has the
 295 popup menu enabled and the 'longest' option as well. When enabled, <tab> will
 296 kick off completion and pre-select the first entry in the popup menu, allowing
 297 you to simply hit <enter> to use it.
 298
 299
 300 Mapping <cr> to end completion      *supertab-crmapping*
 301                                     *g:SuperTabCrMapping*
 302
 303 g:SuperTabCrMapping (default value: 1)
 304
 305 When enabled, <cr> will cancel completion mode preserving the current text.
 306
 307 vim:tw=78:ts=8:ft=help:norl: