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