vim/bundle/space/doc/space.txt @ beeff917055e

*space.txt*   Smart Space Key

                                                                 *space.vim*

     ______  ______   _____   _____  _____
    / _____\ | ___ \ / ___ \ / ___/ / ___/
    \ \____  | ___ / | \ / | | |    | \__ 
     \___  \ | |     | |X| | | |___ | /___
    /______/ \_|     \_/ \_/ \____/ \____/

      By Henrik Öhman <speeph@gmail.com>


                               Reference Manual ~


                                                                 *space-toc*

1. Intro                                               |space-intro|
2. Usage                                               |space-usage|
3. Hooks                                               |space-hooks|
4. Status line integration                             |space-statusline|
5. Configuration                                       |space-configuration|
6. License                                             |space-license|



==============================================================================
1. Intro                                                       *space-intro*

space.vim is a plugin which remaps the *<Space>* key to act as a clever key
to repeat motions. To disable space.vim, set the "space_loaded" global
variable in your |vimrc| file: >
    :let g:space_loaded = 1

space.vim hooks into several of the more complex motion commands, such as
|search-commands|, |jumpto-diffs|, |quickfix| and |location-list| and more
commands. When a command that space.vim has hooked into is issued, it remaps
the <Space> key to repeat that command, and it also remaps <S-Space> and
<BS> to do the reverse.

NOTE:~Due to terminal restrictions, <S-Space> may not be available. For that
reason, the <BS> key is also used for reverse motions. Wherever this document
talks of <S-Space>, <BS> can be used in its place.

NOTE:~space.vim has some problems with the |'foldopen'| option. Since Vim
won't open folds if a command is part of a mapping, space.vim tries to
emulate this behaviour. This works well for all Normal mode mappings and for
most Visual mode mappings. Only for searches using |/| and |?| in Visual mode
is space.vim unable to emulate |'foldopen'|.

NOTE:~Some |filetype| plugins map the section text objects ([[, [], ][, ]])
and the method motions ([m, [M, ]m, ]M). space.vim is unable to hook into
these mappings in a well defined way. There is definitely room for
improvement here.

==============================================================================
2. Usage                                                       *space-usage*

Using space.vim is intuitive. Issue a command, such as a search, and the
<Space> key to go to the next match, and <S-Space> to go to the previous
match. Thus, the following sequence >
    /foo<CR>
    n
    N

is equivalent to >
    /foo<CR>
    <Space>
    <S-Space>

This works with counts, and with Visual mode too >
    /foo<CR>
    V
    4<Space>

space.vim tries to immitate Vim in its logic when specifying the direction for
the repeated movement. For the search commands, <Space> behaves like |n|, and
<S-Space> behaves like |N|, which means that a <Space> following a search using
|?|, will actually find the previous match. For other commands, <Space> is
configured to use the variant of the command that has the meaning of "next".
Thus, <Space> is always mapped to |:lnext|, |[[|, |zj| etc, and never the
reverse.

The full power of space.vim will become apparent if you use |jumpto-diffs|,
in particular on non-US keyboards, or |quickfix| and |location-list|
commands. Remember all that finger stretching and keyboard dancing to quickly
browse through a series of diffs for a fast overview of what your colleague
managed to screw up this time? No more! >
    ]c            Jump to the next diff
    <Space>       Repeat the ]c motion
    ...           Nothing interesting, keep pressing space
    <S-Space>     Wait, there was something! Let's go back one diff

Or why not quickly browse through all files which contain the sentence 'over
9000' in all subdirectories? >
    :lvimgrep /over 9000/ **/*      Find all the matches and add them to the
                                    location-list
    <Space>                         <Space> is now mapped to :lnext
    <S-Space>                       And <S-Space> is mapped to :lprevious

Neat, huh? To get an overview of all the commands space.vim hooks into, and
enables <Space> and <S-Space> mappings for, read on. |space-hooks|

==============================================================================
3. Hooks                                                       *space-hooks*

This is a list of all the commands that space.vim hooks into and provides
<Space> and <S-Space> navigation for.

Character movements:                                    |left-right-motions|
    |f||F||t||T||;||,|

Search commands:                                           |search-commands|
    |star||gstar||#||g#||n||N|

Diff jumps:                                                   |jumpto-diffs|
    |]c||[c|

Parenthesis and bracket jumps:                             |various-motions|
    |])||[(||]}||[{|

Method jumps:                                              |various-motions|
    |]m||[m||]M||[M|

Section jumps:                                              |object-motions|
    |]]||[]||][||[[|

Fold movements:
    |zj||zk||]z||[z|

Quickfix commands:                                                |quickfix|
   |:make|
   |:vimgrep|
   |:grep|
   |:cc|
   |:cnext|
   |:cprevious|
   |:cNext|
   |:cfirst|
   |:clast|
   |:crewind|
   |:cfile|
   |:cnfile|
   |:cpfile|
   |:cNfile|
  
Location list commands:                                      |location-list|
   |:lmake|
   |:lvimgrep|
   |:lgrep|
   |:ll|
   |:lcnext|
   |:lcprevious|
   |:lcNext|
   |:lcfirst|
   |:lclast|
   |:lcrewind|
   |:lcfile|
   |:lcnfile|
   |:lcpfile|
   |:lcNfile|

==============================================================================
4. Status line integration                                *space-statusline*

It is possible to display the current command assigned to <Space> in the
status line using the GetSpaceMovement() function. Here's an example: >

    function! SlSpace()
        if exists("*GetSpaceMovement")
            return "[" . GetSpaceMovement() . "]"
        else
            return ""
        endif
    endfunc
    set statusline+=%{SlSpace()}

==============================================================================
5. Configuration                                       *space-configuration*

It is possible to avoid using the <Space> key for groups of navigation
commands using global variables. For instance, you may wish to use <Space> to
repeat the last command only for diff jumps and quickfix and location list
commands. Here's a list of commands that disable the use of the <Space> key

Disable <Space> for character movements >
    let g:space_no_character_movements = 1

Disable <Space> for search commands >
    let g:space_no_search = 1

Disable <Space> for diff jumps >
    let g:space_no_diff = 1

Disable <Space> for parenthesis and bracket jumps >
    let g:space_no_brace = 1

Disable <Space> for method jumps >
    let g:space_no_method = 1

Disable <Space> for section jumps >
    let g:space_no_section = 1

Disable <Space> for fold movements >
    let g:space_no_folds = 1

Disable <Space> for quickfix and location list commands >
    let g:space_no_quickfix = 1

==============================================================================
6. License                                                   *space-license*

space.vim is licensed under the same terms as Vim itself.
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: