== SearchParty

_Enhanced searches, highlights and matches for Vim_

TIP: If you like SearchParty and want to share the W00t!, I'm grateful for
https://www.gittip.com/bairuidahu/[tips] or
http://of-vim-and-vigor.blogspot.com/[beverages].

== Version 0.7

__July 2016__

* Search Party maps are now defined in `searchparty_user_maps.vim`, the
  loading of which is controlled by `g:searchparty_load_user_maps`.
* Added a new option, `g:searchparty_visual_find_sets_search`:
** 0 (default) -- A visual find operation (`<leader>* / <leader>#`) will
   not set the search register (`@/`).
** 1 -- A visual find operation will set the search register, staying in
   visual mode.
** 2 -- A visual find operation will set the search register, returning
   to normal mode.
* Removed the experimental SearchHighlightReplace functionality.
* Added some tests.

== SearchParty Features

=== User Maps

Search Party provides 18 user-maps and shadows the following eight
built-in normal-mode commands:

  / ? * # g* g# n N

The shadowed commands have been designed to play nice with
https://github.com/henrik/vim-indexed-search[vim-indexed-search] and
https://github.com/osyo-manga/vim-anzu[vim-anzu].

The 18 user-maps have default keys as specified in the
`searchparty_default_maps.vim` file.

If a corresponding `searchparty_user_maps.vim` exists, then all of the
mappings within it will be loaded unless the target has already been
mapped to another key sequence (possibly in your +~/.vimrc+).

If `searchparty_user_maps.vim` doesn't exist, it is created as a copy of
`searchparty_default_maps.vim`.

Customise `searchparty_user_maps.vim` to your needs.

To completely disable the default user-maps processing, add this line
to your +~/.vimrc+:

  let g:searchparty_load_user_maps = 0

=== AfterSearch Event

Functions matching the pattern `/AfterSearch_[0-9]/` will be called in
numeric order after a search operation: `/` `?` `n` `N` `*` `#` `g*`
`g#`.

=== Visual Searches

* +*+  Searches for the next occurrence of the currently selected visual text.
       +<Plug>SearchPartyVisualFindNext+

* +#+  Searches for the prior occurrence of the currently selected visual text.
       +<Plug>SearchPartyVisualFindPrior+

* +&+  Starts a +:substitute+ using the currently selected visual text.
       +<Plug>SearchPartyVisualFindSubstitute+

* +g&+ Repeats the most recent change within the current visual selection.
       +<Plug>SearchPartyVisualChangeAll+

* +gg&+ Just like `g&` but don't put `\<` and `\>` around the word.
       +<Plug>SearchPartyVisualChangeAllBare+

NOTE: The visual mode `g&` map replaces all occurrences of `"-` with `".`
within the current visual selection. The `gg&` version does not wrap the
search term ( `"-` ) within `\<` and `\>` and so occurrences of the word
within other words will also be changed. This is similar to the behaviour of
the existing `*` vs `g*` in Vim.

The option `g:searchparty_visual_find_sets_search` controls whether the
`<Plug>SearchPartyVisualFindNext` and `<Plug>SearchPartyVisualFindPrev`
commands update the current search pattern (`@/`) and whether visual
mode is retained or not. The default value is `0`. The allowed values are:

[cols="1,2",width="55%",options="header"]
|====
|Value | Effects
| 0    | Don't set `@/`. Stay in visual mode. (default)
| 1    | Set `@/`. Stay in visual mode.
| 2    | Set `@/`. Leave visual mode.
|====

To alter this option, add a line like this to your `~/.vimrc`:

  let searchparty_visual_find_sets_search = 1

=== Literal Search

* +<leader>/+   Prompts for a literal string to search for. This does
                NOT use a regular expression, so the characters you type
                here will be searched for literally without any magic
                interpretation. The +<Up>+ key scrolls through prior
                literal search history.
                +<Plug>SearchPartyFindLiteral+

=== Ranged Search

    7,12 RSearch foo

Searches for "foo" only within the range from lines 7 through 12, both
inclusive. The default range is % (the whole buffer).

=== Multiple Replacements

* +<leader>mp+  Prompts for a Search Term and then prompts for
                Replacement Terms (space separated). The current line is
                then duplicated as many times as there are replacements,
                minus one, and the Search Term is then replaced on each
                line with each successive Replacement.

=== Search Highlighting

* +<C-L>+       Temporarily clears search highlight.
                +<Plug>SearchPartyHighlightClear+

* +<C-BSlash>+  Toggles search highlighting.
                +<Plug>SearchPartyHighlightToggle+

* +<leader>*+   Highlights all occurrences of +word+ under the cursor.
                +<Plug>SearchPartyHighlightWord+

* +<leader>mah+ Toggle automatic highlight of all occurrences of +word+
                under cursor.
                NOTE: Update delay determined by +'updatetime'+
                +<Plug>SearchPartyToggleAutoHighlightWord+

* +<leader>g*+  Highlights all occurrences of +WORD+ under the cursor.
                +<Plug>SearchPartyHighlightWORD+

=== Highlighting Print Command

E.g.:

    :g/something/P

Will show the matching lines with all occurrences of `something` on those
lines highlighted.

=== Set Search

* +<leader>ms+  Prompts for a pattern and sets the current search to
                that pattern without moving the cursor to the next
                match of that pattern.
                +<Plug>SearchPartySetSearch+

=== Matches

* +<leader>mm+  Prompts for a pattern and uses +matchadd()+ to highlight all
                occurrences of that pattern in the current window.
                +<Plug>SearchPartySetMatch+
+
There are six match patterns available, called +SPM1+-+SPM6+ respectively.
Using more than six matches will recycle through the SPM set, losing
the previous match assigned to that slot.
+
By default, the terminal palette colours #1-#6 are used for +SPM1+-+SPM6+.
You can override these by providing lines like this in your +~/.vimrc+ file:
+
  hi SPM1 ctermbg=123
+
NOTE: Do this after you have set your colorscheme.

* +<leader>md+  Shows the list of existing matches and prompts for a number
                or pattern to clear. If a number is given, the corresponding
                match is cleared. If a pattern is given, all matching matches
                will be cleared.
                +<Plug>SearchPartyDeleteMatch+

The following functions and commands are available for Search Party matches:

* +SearchPartyMatchDelete(item)+ - clear match by number or pattern
* +SearchPartyMatchList+ - list all match patterns
* +SearchPartyMatchNumber(number)+ - reset match number (+1-6+)

=== M.A.S.H.

Mash is a motion activated (lol - er, I mean, when you press ++n/N/\#/\*/g#/g*++)
current search match highlighter. Breaking that down for you, it highlights
the match under the cursor differently to all the other matches (if you have
:set hlsearch activated). If you don't use hlsearch, then it will still
highlight the current match.

=== Cooperation

SearchParty plays nice with:

* https://github.com/henrik/vim-indexed-search[vim-indexed-search]
* https://github.com/osyo-manga/vim-anzu[vim-anzu]
