sneak.txt

*sneak.txt*  motion improved - Version 1.7.2

                    Sneak - the missing motion for Vim

==============================================================================
1. Overview                                                            *sneak*

Sneak provides a way to move quickly and precisely to locations that would 
be awkward to reach with built-in Vim motions. 

Sneak is invoked with s (sneak forward) or S (sneak backwards), followed by
exactly two characters:

    s{char}{char}

Thus, you can often reach a target with only 3 keystrokes. Sneak always moves 
immediately to the first {char}{char} match. Additional matches are
highlighted, and you can reach them by pressing ; (similar to the built-in 
behavior for |f| and |t|).

Sneak has a few other features, but above all, Sneak tries to get out of your
way: highlights and autocmds are removed as soon as the cursor is moved.

Sneak is tested on 7.2+. Vi-compatibility must be disabled. 'nocompatible'
|sneak-streak-mode| requires Vim 7.3+.

==============================================================================
2. Usage                                                         *sneak-usage*

Sneak is invoked by one of the provided mappings. |sneak-defaults|
You can change these mappings. |sneak-mappings|

Examples (cursor position indicated with brackets []): >

    [L]orem ipsum dolor sit amet, consectetur adipisicing elit
<
Type ssi to go to the beginning of the word "sit": >

    Lorem ipsum dolor [s]it amet, consectetur adipisicing elit
<
Type ; (or 's' again!) to go to the next match: >

    Lorem ipsum dolor sit amet, consectetur adipi[s]icing elit
<
Type Sdo to go backwards to the beginning of the word "dolor": >

    Lorem ipsum [d]olor sit amet, consectetur adipisicing elit
<
Type dzad to delete from the cursor to the first instance of "ad": >

    Lorem ipsum [a]dipisicing elit
<
------------------------------------------------------------------------------
2.1 Default mappings                                          *sneak-defaults*

    Note: See |sneak-mappings| to change these mappings.


NORMAL-mode mappings~

    Key Sequence             | Description
    -------------------------|----------------------------------------------
    s{char}{char}            | Go to the next occurrence of {char}{char}
    S{char}{char}            | Go to the previous occurrence of {char}{char}
    s{char}<Enter>           | Go to the next occurrence of {char}
    S{char}<Enter>           | Go to the previous occurrence of {char}
    s<Enter>                 | Repeat the last Sneak.
    S<Enter>                 | Repeat the last Sneak, in reverse direction.
    ;                        | Go to the [count]'th next match
    , or \                   | Go to the [count]'th previous match
    s                        | Go to the [count]'th next match (see NOTE)
    S                        | Go to the [count]'th previous match (see NOTE)
    [count]s{char}{char}     | Invoke |sneak-vertical-scope|
    [count]S{char}{char}     | Invoke backwards |sneak-vertical-scope|
    {operator}z{char}{char}  | Perform {operator} from the cursor to the next
                             | occurrence of {char}{char}
    {operator}Z{char}{char}  | Perform {operator} from the cursor to the 
                             | previous occurrence of {char}{char}

    NOTE: s and S go to the next/previous match only immediately after
    invoking Sneak; moving the cursor resets this behavior. |sneak-clever-s|


VISUAL-mode mappings~

    Key Sequence             | Description
    -------------------------|----------------------------------------------
    s{char}{char}            | Go to the next occurrence of {char}{char}
    Z{char}{char}            | Go to the previous occurrence of {char}{char}
    s{char}<Enter>           | Go to the next occurrence of {char}
    Z{char}<Enter>           | Go to the previous occurrence of {char}
    s<Enter>                 | Repeat the last Sneak.
    Z<Enter>                 | Repeat the last Sneak, in reverse direction.
    ;                        | Go to the [count]'th next match
    , or \                   | Go to the [count]'th previous match
    s                        | Go to the [count]'th next match (NOTE above)
    S                        | Go to the [count]'th previous match (NOTE above)


STREAK-mode mappings~

    Key Sequence             | Description
    -------------------------|----------------------------------------------
    <space>                  | Exit |sneak-streak-mode| at the current cursor
                             | position.


==============================================================================
3. Features                                                   *sneak-features*

------------------------------------------------------------------------------
3.1 Normal Mode

`s` (and `S`) waits for two characters, then immediately moves to the next
(previous) match. Additional matches are highlighted until the cursor is
moved. Works across multiple lines.

If a |language-mapping| is activated, Sneak waits for keymapped sequences as
needed and searches for the keymapped result as expected. (Requires Vim 7.3+)
'keymap' 'iminsert' |mbyte-keymap|

[count]s enters |sneak-vertical-scope| mode.

`;` and `,` repeat the last `s` and `S`. They also work correctly with `f` and `t`
(unless you or another plugin have mapped `f` or `t` to a custom mapping).
[count]; and [count], skip to the [count]'th match, similar to the
behavior of [count]f and [count]t.

    Note: If your mapleader is |,| then Sneak maps |\| instead of |,|.
    You can override this by specifying some other mapping, eg: >

    nmap gS <Plug>SneakPrevious
<
                                                              *sneak-clever-s*
Similar to the clever-f[3] plugin, immediately after invoking Sneak, you can
move to the next match by simply pressing 's' (or 'S') again. If you instead
move the cursor or do something else, then 's' starts a new Sneak search. In
that case, you can repeat the most recent Sneak search by pressing 's<Enter>'
or whatever (if any) key you mapped to <Plug>SneakNext.

Sneak adds to the |jumplist| only on the initial invocation; so after moving
around with ; and , (or s/S) you can easily go back via |CTRL-O| or |``|.
    - Repeat invocations (;/,) do not add to the jumplist.
    - Consecutive invocations ("s" immediately after s/S/;/,)
      do not add to the jumplist.

s<Enter> ("s" followed by Enter) always repeats the last search, even if |;|
and |,| were reset by |f| or |t|. This is especially useful for re-invoking
|sneak-streak-mode| (because |;| and |,| never invoke streak-mode).

------------------------------------------------------------------------------
3.2 Functions                                                *sneak-functions*

Sneak provides default |sneak-mappings|, but you can call `sneak#` functions
directly if you want customized behavior.

sneak#wrap(op, inputlen, reverse, inclusive, streak)             *sneak#wrap()*
        Invokes Sneak and prompts for exactly {inputlen} characters. For
        example, if {inputlen} is 2, then the match is performed as soon as
        the second character is pressed, without having to press <Enter>.
        {op} may be blank "" or any operation (even custom operations).

        For example, to customize <Plug>Sneak_f:
>
        nnoremap <silent> <Plug>Sneak_f :<c-u>call sneak#wrap('', 1, 0, 1, 0)<cr>
<
            Note: In the example above, <c-u> is required to avoid unwanted
                  |cmdline-ranges| from a [count] or a visual-mode invocation.

sneak#is_sneaking()                                       *sneak#is_sneaking()*
        Returns 1 if Sneak is active (matches are highlighted).
        Returns 0 after the user does anything (which deactivates Sneak and
        removes the highlight). This is useful if you want to change the
        behavior of a mapping based on whether Sneak is active.
            https://github.com/justinmk/vim-sneak/pull/93

        For example, you might want <Tab> to go to the next match _only_ while
        Sneak is active:
>
            nmap <expr> <Tab> sneak#is_sneaking() ? '<Plug>SneakNext' : '<Tab>'
<
sneak#cancel()                                                 *sneak#cancel()*
        Deactivates Sneak (removes autocmds and highlighting) and causes
        `sneak#is_sneaking()` to return 0.
            https://github.com/justinmk/vim-sneak/issues/106

sneak#reset(key)                                                *sneak#reset()*
        Prevents Sneak from hijacking |;| and |,| until the next invocation of
        Sneak. This is useful if you have remapped the Vim built-in |f| or
        |t| to another key and you still want to use |;| and |,| for both Sneak
        and your custom "f" mapping.
            https://github.com/justinmk/vim-sneak/issues/114

        For example, to use "a" as your "f":
>
            nnoremap <expr> a sneak#reset('f')
            nnoremap <expr> A sneak#reset('F')
            xnoremap <expr> a sneak#reset('f')
            xnoremap <expr> A sneak#reset('F')
            onoremap <expr> a sneak#reset('f')
            onoremap <expr> A sneak#reset('F')
<
            Note: The <expr> modifier is required!

sneak#state()                                                   *sneak#state()*
        Returns a read-only dictionary representing the current behavior.

        Values set at invocation (_not_ for repeat):
            KEY             VALUE~
            bounds          [left, right] integer pair representing the current
                            |sneak-vertical-scope| or [0, 0] if not scoped
            inclusive       0: |t|-like motion
                            1: |f|-like motion
                            2: |exclusive| motion like |/|
            input           current search string
            inputlen        length of the current search string
            reverse         0: invoked as forward motion `s`
                            1: invoked as backward motion `S`
            rst             0: |;| and |,| should repeat the most recent Sneak
                            1: after calling |sneak#reset()|

        Values updated on each repeat (|;| |,|):
            KEY             VALUE~
            rptreverse      0: repeat was effectively forward
                            1: repeat was effectively backward

        For example, to create a mapping that behaves differently depending
        on the current Sneak direction (`rptreverse` key):
>
        nmap <silent> <expr> <tab> sneak#is_sneaking()
              \ ? (sneak#state().rptreverse ? '<Plug>(SneakStreakBackward)<cr>' : '<Plug>(SneakStreak)<cr>')
              \ : '<Plug>Sneak_s'
<
------------------------------------------------------------------------------
3.3 Visual Mode

`s` works in visual mode the same as normal mode, however to search backwards
use `Z` (because `S` is taken by the |surround| plugin). `;` and `,` also
work in visual mode as they do in normal mode.

------------------------------------------------------------------------------
3.4 Text Object (for use with an |operator|)

Use `z` for operations; for example, `dzab` deletes from the cursor to the next
instance of "ab". `dZab` deletes backwards to the previous instance.
`czab` `cZab` `yzab` and `yZab` also work as expected.

You can easily map to something other than the default "z" for
operator-pending behavior. |sneak-mappings|

Repeat the operation with dot: |.|
    Note: this requires repeat.vim https://github.com/tpope/vim-repeat

------------------------------------------------------------------------------
3.5 Vertical Scope                                      *sneak-vertical-scope*

Sneak has a unique feature called "vertical scope" search. This is invoked by 
prefixing a normal Sneak search (`s` or `S`) with a [count]. In that case, 
the search is restricted to a column having a width of 2× the [count].

|sneak-vertical-scope| never invokes |sneak-streak-mode|.

Use cases:

    - CSV file
    - hex editing :%!xxd
    - any columnar layout

------------------------------------------------------------------------------
3.6 Streak-Mode                                            *sneak-streak-mode*

Sneak "streak" mode minimizes the number of steps to get to a location, using
a clever interface similar to vim-easymotion[2]. However, there are several
differences (explained below) that make Sneak streak-mode faster, simpler,
and more predictable than vim-easymotion.

To enable "passive" or "smart" streak-mode:                   *g:sneak#streak*
>
    let g:sneak#streak = 1
>
With this setting, Sneak enters streak-mode _only_ if there are ≥2 visible
(on-screen) matches

To force streak-mode always (instead of passively letting Sneak decide when
to enter streak-mode), create a mapping to <Plug>(SneakStreak). For example:
>
    nmap s <Plug>(SneakStreak)
    nmap S <Plug>(SneakStreakBackward)
<
Streak-mode features:

    - automatically jumps to the first match
        - press <Space> or <Esc> to escape streak-mode
        - press <Tab> to skip to the next 56 matches
        - press any key that is _not_ a target label to exit streak-mode and
          immediately perform that key's normal-mode function
    - works with all operators, including |surround|
    - streak-mode edit operations can be repeated and it works correctly
      regardless of the remaining on-screen matches
    - s<Enter> repeats the last sneak search (S<Enter> to change direction)
    - text in |folds| is ignored by streak-mode
        - you can reach folded/off-screen matches with |;| and |,|

As always, you can:
    - skip to the next or previous match with |;| or |,|
    - return to your original location via |CTRL-O| or |``|

Note: If `s` is prefixed with a [count] then |sneak-vertical-scope| is invoked
      and streak-mode will _not_ be invoked.

==============================================================================
4. Configuration                                         *sneak-configuration*

Sneak is designed with sane, effective defaults, to avoid configuration as
much as possible; but you can change them as follows.

------------------------------------------------------------------------------
4.1 Options                                                    *sneak-options*

To change an option, add a |let| statement in your |vimrc|. For example: >

    let g:sneak#use_ic_scs = 0
<
Following is a list of Sneak options with their default values.

g:sneak#f_reset = 1
g:sneak#t_reset = 1

    Note: if you mapped f (or t) to a |sneak-mappings| then the default is 0.

    0 : Pressing |f| (or |t|) will NOT clear the last Sneak search. So you could
        define different maps for <Plug>SneakNext or <Plug>SneakPrevious and
        still use ; and , for |f| and |t| as usual.

    1 : Pressing |f| (or |t|) causes Sneak to "reset" so that |;| and |,| will apply
        to the last f (or t) motion instead of the last s or S. This makes it
        possible to use ; and , for all three motions (f, t, and s).

        Note: if f (or t) was already mapped by you or a plugin, Sneak will
        not override the existing mapping unless you explicitly set f_reset
        (or t_reset). This means Sneak will not be able to reset ; or , when
        you invoke f or t. See the README.md FAQ regarding "f-enhancement"
        plugins.

g:sneak#s_next = 0

    0 : Disable "clever-s" behavior. Use |;| and |,| to go to the next or
        previous match.

    1 : Enable the "clever-s" feature (similar to the clever-f plugin[3]).
        It works like this: immediately after invoking Sneak, press "s" _again_
        to go to the next match, or "S" for the previous match. This behavior
        persists until you move the cursor.
        Note: You can still use |;| and |,| as usual.

g:sneak#absolute_dir = 0

    0 : Relative direction. |;| goes to the next match in the direction of the
        initial s/S invocation and |,| goes in the opposite direction.

    1 : Absolute direction. Repeat via |;| or |,| always goes forwards or
        backwards respectively.
        Note: With |sneak-clever-s|, s and S behave the same as |;| and |,|.

g:sneak#textobject_z = 1

    0 : Prevent the default {operator}z mapping. You can map to something
        else, see |sneak-mappings|.

    1 : Allow the default {operator}z mapping.

g:sneak#use_ic_scs = 0

    0 : Always case-sensitive

    1 : Case sensitivity is determined by 'ignorecase' and 'smartcase'.

g:sneak#map_netrw = 1

    0 : Don't do any special handling of "file manager" buffers (such as
        |netrw| or filebeagle).

    1 : Set up Sneak mappings (s and S) in "file manager" buffers (|:Ex|,
        |:Vex|, filebeagle) and replace the default buffer-local s and
        S mappings with <leader>s and <leader>S.

g:sneak#streak = 0

    0 : Disable |sneak-streak-mode|.

    1 : Enable |sneak-streak-mode| if the Vim |+conceal| feature is available.

g:sneak#streak_esc = "\<space>"

    Exit |sneak-streak-mode| as if <esc> were pressed.
        https://github.com/justinmk/vim-sneak/issues/122

g:sneak#target_labels = "asdfghjkl;qwertyuiopzxcvbnm/ASDFGHJKL:QWERTYUIOPZXCVBNM?"

    List of 1-character "labels" used by streak-mode to decorate the target
    locations.

    Note: If ; (or any key mapped to <Plug>SneakNext) is in the list, Sneak
    automatically moves it to the first position (because it's semantically
    equivalent and it saves a target label).

    Note: Invalid target labels are automatically removed:
        - Any key mapped to <Plug>SneakPrevious
        - <Esc>, <Tab>, <BS>, because they are special
        - <Space>, <Enter>, because they are invisible

g:sneak#prompt = '>'

        Message displayed at the Sneak input prompt.

------------------------------------------------------------------------------
4.2 Custom Highlighting                                      *sneak-highlight*

Sneak uses the following highlight groups:

    SneakPluginTarget
        Highlights additional matches. Default color is hideous magenta :)

    SneakPluginScope
        Highlights the search "scope" for |sneak-vertical-scope|.
        Default color is white (or black if background=light)

    SneakStreakTarget
        Highlights matches for |sneak-streak-mode|.

    SneakStreakMask
        Used to de-emphasize un-labeled matches and the "tail" of labeled
        matches in |sneak-streak-mode|, so the target label is easier to see.

    SneakStreakStatusLine
        Decorates the statusline during |sneak-streak-mode|. This only works
        if you use the default |hl-StatusLine| highlight group; it probably
        won't work if you use a statusline plugin like Powerline.

There are three ways to override the default colors (listed in order of
decreasing elegance):

    1. Link to existing highlight groups (for example, "ErrorMsg" and
       "Comment") so that the colors are implicitly chosen by your
       currently-activated colorscheme: >

       hi link SneakPluginTarget ErrorMsg
       hi link SneakPluginScope  Comment
<
    2. To define specific colors _regardless_ of the current colorscheme, you
       probably need to define an |autocmd| on the |ColorScheme| event
       (otherwise the colorscheme will clear the highlights): >

       augroup SneakPluginColors
           autocmd!
           autocmd ColorScheme * hi SneakPluginTarget guifg=black guibg=red ctermfg=black ctermbg=red
           autocmd ColorScheme * hi SneakPluginScope  guifg=black guibg=yellow ctermfg=black ctermbg=yellow
       augroup END
<
    3. Edit your color scheme directly: >

       hi SneakPluginTarget guifg=black guibg=red ctermfg=black ctermbg=red
       hi SneakPluginScope  guifg=black guibg=yellow ctermfg=black ctermbg=yellow
<
------------------------------------------------------------------------------
4.3 Custom Mappings                                           *sneak-mappings*

Sneak provides <Plug> mappings for you to specify alternative key maps.
Keep in mind, however, that motion mappings should absolutely be the
least-friction mappings in your editor, because motion is the most common
editor task; mapping Sneak to something like <leader>s is not recommended.

You can remap any Sneak feature by defining any of these <Plug> mappings in
your |vimrc|: >

    " 2-character Sneak (default)
    nmap ? <Plug>Sneak_s
    nmap ? <Plug>Sneak_S
    " visual-mode
    xmap ? <Plug>Sneak_s
    xmap ? <Plug>Sneak_S
    " operator-pending-mode
    omap ? <Plug>Sneak_s
    omap ? <Plug>Sneak_S

    " explicit repeat (as opposed to implicit 'clever-s' repeat)
    map ? <Plug>SneakNext
    map ? <Plug>SneakPrevious

    " 1-character enhanced 'f'
    nmap ? <Plug>Sneak_f
    nmap ? <Plug>Sneak_F
    " visual-mode
    xmap ? <Plug>Sneak_f
    xmap ? <Plug>Sneak_F
    " operator-pending-mode
    omap ? <Plug>Sneak_f
    omap ? <Plug>Sneak_F

    " 1-character enhanced 't'
    nmap ? <Plug>Sneak_t
    nmap ? <Plug>Sneak_T
    " visual-mode
    xmap ? <Plug>Sneak_t
    xmap ? <Plug>Sneak_T
    " operator-pending-mode
    omap ? <Plug>Sneak_t
    omap ? <Plug>Sneak_T

    " force streak-mode always
    nmap ? <Plug>(SneakStreak)
    nmap ? <Plug>(SneakStreakBackward)
<
Here are some examples: >

    nmap gs <Plug>Sneak_s
    nmap gS <Plug>Sneak_S
    xmap gs <Plug>Sneak_s
    xmap gS <Plug>Sneak_S
    omap gs <Plug>Sneak_s
    omap gS <Plug>Sneak_S

    nmap <Space> <Plug>(SneakStreak)

    nmap <enter> <Plug>SneakNext
    xmap <enter> <Plug>SneakNext
    nmap <bs>    <Plug>SneakPrevious
    xmap <bs>    <Plug>SneakPrevious

    " by default, Sneak does not touch 'f' or 't', so if you want
    " 1-character Sneak for 'f' or 't', do the following.
    nmap f <Plug>Sneak_f
    nmap F <Plug>Sneak_F
    xmap f <Plug>Sneak_f
    xmap F <Plug>Sneak_F
    omap f <Plug>Sneak_f
    omap F <Plug>Sneak_F
<
==============================================================================
5. Contributing                                           *sneak-contributing*

Bug reports, feature requests, and pull requests are welcome:

    https://github.com/justinmk/vim-sneak

In your bug report, it is helpful to include the output of this command: >

    :call sneak#debug#report()

If you are feeling diligent: to narrow down the cause of the issue, you can
run Vim without any plugins except sneak.vim like this: >

    vim -u NONE -N -c ':set runtimepath+=~/.vim/bundle/vim-sneak/' -c ':runtime plugin/sneak.vim'
<
==============================================================================
6. Credits                                                     *sneak-credits*

Author: Justin M. Keyes <justinkz+vim@gmail.com>

Sneak was inspired by vim-seek[1], vim-easymotion[2], and clever-f[3].

Tim Pope's plugin sources were used for reference and best practices.

easymotion.txt was used for the initial version of this document.

[1] https://github.com/goldfeld/vim-seek
[2] https://github.com/Lokaltog/vim-easymotion
[3] https://github.com/rhysd/clever-f.vim

==============================================================================
vim:tw=78:sw=4:ts=8:ft=help:norl: