DESCRIPTION
The mappings, command and operator provided by this plugin search a range or
the entire buffer for a pattern (defaulting to the last search pattern),
and print a summary of the number of occurrences above, below and on the
current line, e.g.:
1 match after cursor in this line, 8 following, 2 in previous lines;
total 10 within 11,42 for /\<SearchPosition\>/

On sole match in this line, 40 in following lines within 24,171 for /let/

:144,172 7 matches in this fold for /let/

This provides better orientation in a buffer without having to first jump from
search result to search result.

MOTIVATION
In its simplest implementation
:nnoremap <A-n> :%s///gn<CR>
41 matches on 17 lines
prints the number of matches for the last search pattern. This plugin
builds on top of this by providing more context with regards to the current
cursor position plus additional information.

This plugin is similar to IndexedSearch.vim (vimscript #1682) by Yakov Lerner.

USAGE
:[range]SearchPosition [/][{pattern}][/]
Show position of the search results for {pattern} (or
the last search pattern (quote/) if {pattern} is
omitted). Without [/], only literal whole words are
matched. :search-args
All lines in [range] (or the entire buffer
if omitted) are considered, and the number of matches
in relation to the current cursor position is echoed
to the command line.

:[range]SearchPositionMultiple /{pattern1}/,/{pattern2}/[,...]
:[range]SearchPositionMultiple {word1},{word2}[,...]
Show positions and tallies of the search results for
{pattern1}, {pattern2}, ... Without [/] delimiters,
only literal whole {word1}, {word2}, ... are matched.
:search-args Useful to compare the number of
occurrences for multiple variants.

<Leader><A-n>{motion} Show position for the last search pattern in the
lines covered by {motion}.
[count]<A-n> Show position for the last search pattern in the
entire buffer, or [count] following lines.
{Visual}<A-n> Show position for the last search pattern in the
selected lines.

The default mapping <A-n> was chosen because one often
invokes this when jumping to matches via n/N, so <A-n>
is easy to reach. Imagine 'n' stood for "next
searches".

[count]<A-m> Show position for the whole word under the cursor in
the entire buffer, or [count] following lines.
Only whole keywords are searched for, like with the
star command.
[count]g<A-m> Show position for the word under the cursor in the
entire buffer, or [count] following lines.
Also finds contained matches, like gstar.

{Visual}<A-m> Show position for the selected text in the entire
buffer.

Imagine 'm' stood for "more occurrences".
These mappings reuse the last used <cword> when issued
on a blank line.

install details

INSTALLATION
This script is packaged as a vimball. If you have the "gunzip" decompressor
in your PATH, simply edit the *.vmb.gz package in Vim; otherwise, decompress
the archive first, e.g. using WinZip. Inside Vim, install by sourcing the
vimball or via the :UseVimball command.
vim SearchPosition*.vmb.gz
:so %
To uninstall, use the :RmVimball command.

CONFIGURATION
For a permanent configuration, put the following commands into your vimrc:

The highlight group for the report message can be set via
let g:SearchPosition_HighlightGroup = 'ModeMsg'

To shorten the report message, the [range] and used search pattern can be
omitted from the message; by default, both are included in the message text:
let g:SearchPosition_ShowRange = 1
let g:SearchPosition_ShowPattern = 1

The report also shows in which range the matches fall. To turn this off:
let g:SearchPosition_ShowMatchRange = 1

If the range falls entirely into the lines that are shown in the current
window, a relative range is used. To prefer a fixed threshold, or to turn this
off, use:
let g:SearchPosition_MatchRangeShowRelativeThreshold = 10
The relative threshold at the end is determined via:
let g:SearchPosition_MatchRangeShowRelativeEndThreshold = 10

- BUG: Also need to account for cursor within closed fold for the start line number, not just the end.
- Also submit the plugin's result message (in unhighlighted form) to the message history (for recall and comparison).
- Add :SearchPositionMultiple command.
- Tweak s:TranslateLocation() for line 1: :2 looks better than :.+1 there.
- Tweak s:TranslateLocation() for last line and use :$-N instead of :.-N there.
- BUG: Incorrect de-pluralization of "11 match[es]". *** You need to update to ingo-library (vimscript #4433) version 1.022! ***

- ENH: Show relative range when the lines are shown in the current window with a new default configuration value of "visible" for g:SearchPosition_MatchRangeShowRelativeThreshold. Use separate g:SearchPosition_MatchRangeShowRelativeEndThreshold for threshold at the end.
- FIX: After "Special atoms have distorted the tally" warning, an additional stray (last actual) error is repeated. s:Report() also needs to return 1 after such warning.
- BUG: "Special atoms have distorted the tally" warning instead of "No matches" when on first line. Must not allow previous matching line when that is identical to 0, the return value of search() when it fails.
- BUG: "Special atoms have distorted the tally" when doing :SearchPosition/\n\n/ on empty line. The special case for \n matching is actually more complex; need to also ensure that the match doesn't lie completely on the previous line, and retry without the "c" search flag if it does.

- Abort commands and mappings on error.
- Use SearchPosition#OperatorExpr() to also handle [count] before the operator mapping.
- CHG: Also allow :[range]SearchPosition /{pattern}/ argument syntax; make previous :SearchPosition {pattern} do a literal whole word search.
- ENH: Also show range that the matches fall into; locations close to the current line in relative form.
- Add dependency to ingo-library (vimscript #4433). *** You need to separately install ingo-library (vimscript #4433) version 1.020 (or higher)! ***

- BUG: Visual mode <A-m> /Plug>SearchPositionCword mapping on multi-line selection searched for ^@, not the newline character \n.
- BUG: Incorrect reporting of sole match in folded line when the current line is empty and the pattern starts matching a newline character.
- Using SearchPosition#SavePosition() instead ofVim version-dependent) mark to keep the cursor at the position where the operator was invokedonly necessary with a backward {motion}).

- Moved functions from plugin to separate autoload script.
- BUG: Wrong reporting of additional occurrences when the current line is outside the passed range.
- BUG: Catch non-existing items in evaluations that can be caused by e.g having \%# inside the search pattern. Warn about "special atoms have distorted the tally" in such cases.