Space plugin.
[profile.git] / .vim / doc / space.txt
1 *space.txt*   Smart Space Key
2
3                                                                  *space.vim*
4
5      ______  ______   _____   _____  _____
6     / _____\ | ___ \ / ___ \ / ___/ / ___/
7     \ \____  | ___ / | \ / | | |    | \__
8      \___  \ | |     |  V  | | |___ | /___
9     /______/ \_|     \_/ \_/ \____/ \____/
10
11       By Henrik Öhman <speeph@gmail.com>
12
13
14                                Reference Manual ~
15
16
17                                                                  *space-toc*
18
19 1. Intro                                               |space-intro|
20 2. Usage                                               |space-usage|
21 3. Hooks                                               |space-hooks|
22 4. Status line integration                             |space-statusline|
23 5. Configuration                                       |space-configuration|
24 6. License                                             |space-license|
25
26
27
28 ==============================================================================
29 1. Intro                                                       *space-intro*
30
31 space.vim is a plugin which remaps the *<Space>* key to act as a clever key
32 to repeat motions. To disable space.vim, set the "space_loaded" global
33 variable in your |vimrc| file: >
34     :let g:space_loaded = 1
35
36 space.vim hooks into several of the more complex motion commands, such as
37 |search-commands|, |jumpto-diffs|, |quickfix|, |tag-commands| and
38 |location-list| and more commands. When a command that space.vim has hooked
39 into is issued, it remaps the <Space> key to repeat that command, and it also
40 remaps <S-Space> and <BS> to do the reverse.
41
42 NOTE:~Due to terminal restrictions, <S-Space> may not be available. For that
43 reason, the <BS> key is also used for reverse motions. Wherever this document
44 talks of <S-Space>, <BS> can be used in its place.
45
46 NOTE:~When using the gVim space.vim won't remap <BS> if any previous mappings
47 to it already exists. When using Vim <BS> is always remapped.
48
49 NOTE:~space.vim has some problems with the |'foldopen'| option. Since Vim
50 won't open folds if a command is part of a mapping, space.vim tries to
51 emulate this behaviour. This works well for all Normal mode mappings and for
52 most Visual mode mappings. Only for searches using |/| and |?| in Visual mode
53 is space.vim unable to emulate |'foldopen'|.
54
55 NOTE:~Some |filetype| plugins map the section text objects ([[, [], ][, ]])
56 and the method motions ([m, [M, ]m, ]M). space.vim is unable to hook into
57 these mappings in a well defined way. There is definitely room for
58 improvement here.
59
60 ==============================================================================
61 2. Usage                                                       *space-usage*
62
63 Using space.vim is intuitive. Issue a command, such as a search, and the
64 <Space> key to go to the next match, and <S-Space> to go to the previous
65 match. Thus, the following sequence >
66     /foo<CR>
67     n
68     N
69
70 is equivalent to >
71     /foo<CR>
72     <Space>
73     <S-Space>
74
75 This works with counts, and with Visual mode too >
76     /foo<CR>
77     V
78     4<Space>
79
80 space.vim tries to immitate Vim in its logic when specifying the direction for
81 the repeated movement. For the search commands, <Space> behaves like |n|, and
82 <S-Space> behaves like |N|, which means that a <Space> following a search using
83 |?|, will actually find the previous match. For other commands, <Space> is
84 configured to use the variant of the command that has the meaning of "next".
85 Thus, <Space> is always mapped to |:lnext|, |[[|, |zj| etc, and never the
86 reverse.
87
88 The full power of space.vim will become apparent if you use |jumpto-diffs|,
89 in particular on non-US keyboards, or |quickfix| and |location-list|
90 commands. Remember all that finger stretching and keyboard dancing to quickly
91 browse through a series of diffs for a fast overview of what your colleague
92 managed to screw up this time? No more! >
93     ]c            Jump to the next diff
94     <Space>       Repeat the ]c motion
95     ...           Nothing interesting, keep pressing space
96     <S-Space>     Wait, there was something! Let's go back one diff
97
98 Or why not quickly browse through all files which contain the sentence 'over
99 9000' in all subdirectories? >
100     :lvimgrep /over 9000/ **/*      Find all the matches and add them to the
101                                     location-list
102     <Space>                         <Space> is now mapped to :lnext
103     <S-Space>                       And <S-Space> is mapped to :lprevious
104
105 Neat, huh? To get an overview of all the commands space.vim hooks into, and
106 enables <Space> and <S-Space> mappings for, read on. |space-hooks|
107
108 ==============================================================================
109 3. Hooks                                                       *space-hooks*
110
111 This is a list of all the commands that space.vim hooks into and provides
112 <Space> and <S-Space> navigation for.
113
114 Character movements:                                    |left-right-motions|
115     |f| |F| |t| |T| |;| |,|
116
117 Search commands:                                           |search-commands|
118     |star| |gstar| |#| |g#| |n| |N|
119
120 Jump list jumps:                                              |jump-motions|
121     |CTRL-O| |CTRL-I|
122
123 Change list jumps:                                       |change-list-jumps|
124     |g;| |g,|
125
126 Diff jumps:                                                   |jumpto-diffs|
127     |]c| |[c|
128
129 Parenthesis and bracket jumps:                             |various-motions|
130     |])| |[(| |]}| |[{|
131
132 Method jumps:                                              |various-motions|
133     |]m| |[m| |]M| |[M|
134
135 Section jumps:                                              |object-motions|
136     |]]| |[]| |][| |[[|
137
138 Fold movements:
139     |zj| |zk| |]z| |[z|
140
141 Tag movements:                                                |tag-commands|
142     |CTRL-]|
143     |:tag|
144     |:tnext|
145     |:tprevious|
146     |:tNext|
147     |:trewind|
148     |:tfirst|
149     |:tlast|
150
151 Undolist movements:                                          |undo-branches|
152     |g-||g+|
153
154 Quickfix commands:                                                |quickfix|
155     |:make|
156     |:vimgrep|
157     |:grep|
158     |:cc|
159     |:cnext|
160     |:cprevious|
161     |:cNext|
162     |:cfirst|
163     |:clast|
164     |:crewind|
165     |:cfile|
166     |:cnfile|
167     |:cpfile|
168     |:cNfile|
169
170 Location list commands:                                      |location-list|
171     |:lmake|
172     |:lvimgrep|
173     |:lgrep|
174     |:ll|
175     |:lcnext|
176     |:lcprevious|
177     |:lcNext|
178     |:lcfirst|
179     |:lclast|
180     |:lcrewind|
181     |:lcfile|
182     |:lcnfile|
183     |:lcpfile|
184     |:lcNfile|
185
186 ==============================================================================
187 4. Status line integration                                *space-statusline*
188
189 It is possible to display the current command assigned to <Space> in the
190 status line using the GetSpaceMovement() function. Here's an example: >
191
192     function! SlSpace()
193         if exists("*GetSpaceMovement")
194             return "[" . GetSpaceMovement() . "]"
195         else
196             return ""
197         endif
198     endfunc
199     set statusline+=%{SlSpace()}
200
201 ==============================================================================
202 5. Configuration                                       *space-configuration*
203
204 It is possible to avoid using the <Space> key for groups of navigation
205 commands using global variables. For instance, you may wish to use <Space> to
206 repeat the last command only for diff jumps and quickfix and location list
207 commands. Here's a list of commands that disable the use of the <Space> key
208
209 Disable <Space> for character movements >
210     let g:space_no_character_movements = 1
211
212 Disable <Space> for search commands >
213     let g:space_no_search = 1
214
215 Disable <Space> for jump commands >
216     let g:space_no_jump = 1
217
218 Disable <Space> for diff jumps >
219     let g:space_no_diff = 1
220
221 Disable <Space> for parenthesis and bracket jumps >
222     let g:space_no_brace = 1
223
224 Disable <Space> for method jumps >
225     let g:space_no_method = 1
226
227 Disable <Space> for section jumps >
228     let g:space_no_section = 1
229
230 Disable <Space> for fold movements >
231     let g:space_no_folds = 1
232
233 Disable <Space> for tag movements >
234     let g:space_no_tags = 1
235
236 Disable <Space> for quickfix and location list commands >
237     let g:space_no_quickfix = 1
238
239 Disable <Space> for undolist movements >
240     let g:space_no_undolist = 1
241
242 Furthermore it is possible to disable the hooks and mappings set by space.vim
243 to affect the select mode (these can cause problems with some snippets plugins
244 like snipmate.vim) >
245     let g:space_disable_select_mode = 1
246
247 ==============================================================================
248 6. License                                                   *space-license*
249
250 space.vim is licensed under the same terms as Vim itself.
251
252 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: