1 *space.txt* Smart Space Key
5 ______ ______ _____ _____ _____
6 / _____\ | ___ \ / ___ \ / ___/ / ___/
7 \ \____ | ___ / | \ / | | | | \__
8 \___ \ | | | V | | |___ | /___
9 /______/ \_| \_/ \_/ \____/ \____/
11 By Henrik Öhman <speeph@gmail.com>
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|
28 ==============================================================================
29 1. Intro *space-intro*
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
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.
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.
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.
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'|.
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
60 ==============================================================================
61 2. Usage *space-usage*
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 >
75 This works with counts, and with Visual mode too >
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
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
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
102 <Space> <Space> is now mapped to :lnext
103 <S-Space> And <S-Space> is mapped to :lprevious
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|
108 ==============================================================================
109 3. Hooks *space-hooks*
111 This is a list of all the commands that space.vim hooks into and provides
112 <Space> and <S-Space> navigation for.
114 Character movements: |left-right-motions|
115 |f| |F| |t| |T| |;| |,|
117 Search commands: |search-commands|
118 |star| |gstar| |#| |g#| |n| |N|
120 Jump list jumps: |jump-motions|
123 Change list jumps: |change-list-jumps|
126 Diff jumps: |jumpto-diffs|
129 Parenthesis and bracket jumps: |various-motions|
132 Method jumps: |various-motions|
135 Section jumps: |object-motions|
141 Tag movements: |tag-commands|
151 Undolist movements: |undo-branches|
154 Quickfix commands: |quickfix|
170 Location list commands: |location-list|
186 ==============================================================================
187 4. Status line integration *space-statusline*
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: >
193 if exists("*GetSpaceMovement")
194 return "[" . GetSpaceMovement() . "]"
199 set statusline+=%{SlSpace()}
201 ==============================================================================
202 5. Configuration *space-configuration*
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
209 Disable <Space> for character movements >
210 let g:space_no_character_movements = 1
212 Disable <Space> for search commands >
213 let g:space_no_search = 1
215 Disable <Space> for jump commands >
216 let g:space_no_jump = 1
218 Disable <Space> for diff jumps >
219 let g:space_no_diff = 1
221 Disable <Space> for parenthesis and bracket jumps >
222 let g:space_no_brace = 1
224 Disable <Space> for method jumps >
225 let g:space_no_method = 1
227 Disable <Space> for section jumps >
228 let g:space_no_section = 1
230 Disable <Space> for fold movements >
231 let g:space_no_folds = 1
233 Disable <Space> for tag movements >
234 let g:space_no_tags = 1
236 Disable <Space> for quickfix and location list commands >
237 let g:space_no_quickfix = 1
239 Disable <Space> for undolist movements >
240 let g:space_no_undolist = 1
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
245 let g:space_disable_select_mode = 1
247 ==============================================================================
248 6. License *space-license*
250 space.vim is licensed under the same terms as Vim itself.
252 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: