]> git.r.bdr.sh - rbdr/dotfiles/blame - vim/doc/supertab.txt
A whole bunch of new additions to the submodules
[rbdr/dotfiles] / vim / doc / supertab.txt
CommitLineData
0d23b6e5
BB
1*supertab.txt*
2
3Authors:
4 Original: Gergely Kontra <kgergely@mcl.hu>
5 Current: Eric Van Dewoestine <ervandew@gmail.com> (as of version 0.4)
6
7Contributors:
8 Christophe-Marie Duquesne <chm.duquesne@gmail.com> (documentation)
9
10Please direct all correspondence to Eric.
11
12This plugin is licensed under the terms of the BSD License. Please see
13supertab.vim for the license in its entirety.
14
15==============================================================================
16Supertab *supertab*
17
181. Introduction |supertab-intro|
192. Supertab Usage |supertab-usage|
203. 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==============================================================================
351. Introduction *supertab-intro*
36
37Supertab is a plugin which allows you to perform all your insert completion
38(|ins-completion|) using the tab key.
39
40Supertab requires Vim version 7.0 or above.
41
42==============================================================================
432. Supertab usage *supertab-usage*
44
45Using Supertab is as easy as hitting <Tab> or <S-Tab> (shift+tab) while in
46insert mode, with at least one non whitespace character before the cursor, to
47start the completion and then <Tab> or <S-Tab> again to cycle forwards or
48backwards through the available completions.
49
50Example ('|' denotes the cursor location):
51
52bar
53baz
54b|<Tab> Hitting <Tab> here will start the completion, allowing you to
55 then cycle through the suggested words ('bar' and 'baz').
56
57==============================================================================
583. Supertab Options *supertab-options*
59
60Supertab 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
62the variables available.
63
64
65Default Completion Type *supertab-defaultcompletion*
66 *g:SuperTabDefaultCompletionType*
67
68g:SuperTabDefaultCompletionType (default value: "<c-p>")
69
70Used to set the default completion type. There is no need to escape this
71value 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
77Note: a special value of 'context' is supported which will result in
78super tab attempting to use the text preceding the cursor to decide which
79type of completion to attempt. Currently super tab can recognize method
80calls or attribute references via '.', '::' or '->', and file path
81references 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
90When using context completion, super tab will fall back to a secondary default
91completion type set by |g:SuperTabContextDefaultCompletionType|.
92
93Note: once the buffer has been initialized, changing the value of this setting
94will not change the default complete type used. If you want to change the
95default completion type for the current buffer after it has been set, perhaps
96in an ftplugin, you'll need to call SuperTabSetDefaultCompletionType like so,
97supplying the completion type you wish to switch to:
98
99 call SuperTabSetDefaultCompletionType("<c-x><c-u>")
100
101
102Secondary default completion type *supertab-contextdefault*
103 *g:SuperTabContextDefaultCompletionType*
104
105g:SuperTabContextDefaultCompletionType (default value: "<c-p>")
106
107Sets the default completion type used when g:SuperTabDefaultCompletionType is
108set to 'context' and no completion type is returned by any of the configured
109contexts.
110
111
112Completion contexts *supertab-completioncontexts*
113 *g:SuperTabCompletionContexts*
114
115g:SuperTabCompletionContexts (default value: ['s:ContextText'])
116
117Sets the list of contexts used for context completion. This value should
118be a list of function names which provide the context implementation.
119
120When supertab starts the default completion, each of these contexts will be
121consulted, in the order they were supplied, to determine the completion type
122to use. If a context returns a completion type, that type will be used,
123otherwise the next context in the list will be consulted. If after executing
124all the context functions, no completion type has been determined, then the
125value of g:SuperTabContextDefaultCompletionType will be used.
126
127Built 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
190Completion Duration *supertab-duration*
191 *g:SuperTabRetainCompletionDuration*
192
193g:SuperTabRetainCompletionDuration (default value: 'insert')
194
195Determines if, and for how long, the current completion type is retained.
196The 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
209Preventing completion after... *supertab-preventcomplete*
210 *g:SuperTabNoCompleteBefore*
211 *g:SuperTabNoCompleteAfter*
212
213g:SuperTabNoCompleteBefore (default value: [])
214g:SuperTabNoCompleteAfter (default value: ['\s'])
215
216These two variables are used to control when supertab will attempt completion
217or instead fall back to inserting a literal <tab>, by specifying a list of
218patterns which are tested against the text before and after the current cursor
219position that when matched, prevent completion. So if you don't want supertab
220to start completion after a comma or space, you can set
221g:SuperTabNoCompleteAfter to [',', '\s'].
222
223Note: That a buffer local version of these variables
224(b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) is also supported
225should you wish to have different values depending on the file type for
226instance.
227
228Changing the default mapping *supertab-forwardbackward*
229 *g:SuperTabMappingForward*
230 *g:SuperTabMappingBackward*
231
232g:SuperTabMappingForward (default value: '<tab>')
233g:SuperTabMappingBackward (default value: '<s-tab>')
234
235These two variables allow you to set the keys used to kick off the current
236completion. By default this is <tab> and <s-tab>. To change to something
237like <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
242Note: if the above does not have the desired effect (which may happen in
243console version of vim), you can try the following mappings. Although the
244backwards mapping still doesn't seem to work in the console for me, your
245milage may vary.
246
247 let g:SuperTabMappingForward = '<nul>'
248 let g:SuperTabMappingBackward = '<s-nul>'
249
250
251Inserting true tabs *supertab-mappingtabliteral*
252 *g:SuperTabMappingTabLiteral*
253
254g:SuperTabMappingTabLiteral (default value: '<c-tab>')
255
256Sets the key mapping used to insert a literal tab where supertab would
257otherwise 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
259using a console vim and want this functionality, you may have to change it to
260something that is supported. Alternatively, you can escape the <tab> with
261<c-v> (see |i_CTRL-V| for more infos).
262
263
264Enhanced longest match support *supertab-longestenhanced*
265 *g:SuperTabLongestEnhanced*
266
267g:SuperTabLongestEnhanced (default value: 0)
268
269When enabled and 'longest' is in your |completeopt| setting, supertab will
270provide an enhanced longest match support where typing one or more letters and
271hitting tab again while in a completion mode will complete the longest common
272match using the new text in the buffer.
273
274For example, say you have a buffer with the following contents:
275 FooBarFoo
276 FooBar
277 Foo
278 FooBarBaz
279And you then type F<tab>. Vim's builtin longest support will complete the
280longest common text 'Foo' and offer 'FooBarFoo', 'FooBar', 'Foo', and
281'FooBarBaz' as possible completions. With supertab's longest match
282enhancement disabled, typing B<tab> while still in the completion mode will
283end up completing 'FooBarBaz' or 'FooBarFoo' depending your settings, instead
284of the next longest common match of 'FooBar'. With supertab's enhanced
285longest match feature enabled, the typing of B<tab> will result in the next
286longest text being completed.
287
288
289Preselecting the first entry *supertab-longesthighlight*
290 *g:SuperTabLongestHighlight*
291
292g:SuperTabLongestHighlight (default value: 0)
293
294Sets whether or not to pre-highlight the first match when completeopt has the
295popup menu enabled and the 'longest' option as well. When enabled, <tab> will
296kick off completion and pre-select the first entry in the popup menu, allowing
297you to simply hit <enter> to use it.
298
299
300Mapping <cr> to end completion *supertab-crmapping*
301 *g:SuperTabCrMapping*
302
303g:SuperTabCrMapping (default value: 1)
304
305When enabled, <cr> will cancel completion mode preserving the current text.
306
307vim:tw=78:ts=8:ft=help:norl: