.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: