sponsor Vim development Vim logo Vim Book Ad

SearchSpecial : Generic functions for special search modes.

 script karma  Rating 0/0, Downloaded by 1476  Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
The built-in search via /, n, and N does its job. But sometimes, it
would be nice to have a custom search that is limited to a certain range, or
the first match in a line, or certain syntax groups, or a search that doesn't
open folds. This plugin offers generic functions that can be used to easily
build such custom search mappings for special searches. A predicate function
can specify which matches are skipped, and options control the behavior with
regards to folding and jumps.

- The SearchRepeat.vim (vimscript #4949) plugin provides an integration
  facility for custom searches (such as ones implemented via
  SearchSpecial.vim) that repeats the last type of used search via n/N, and
  can list all defined custom searches.

The following custom searches use this plugin:

- SearchAsQuickJump.vim (vimscript #5619):
  Quick search without affecting 'hlsearch', search pattern and history.

This plugin defines several functions. The following is an overview; you'll
find the details directly in the implementation files in the .vim/autoload/

SearchSpecial#SearchWithout( searchPattern, isBackward, Predicate, predicateId, predicateDescription, count, ... )

The main helper function that jumps to the next match of a:searchPattern,
skipping all those matches where a:Predicate returns false.

Here's a simple search mapping that emulates the default search (because it
doesn't pass a predicate that limits the matches, nor are there any options):
    nnoremap <silent> ,n
    \   :<C-u>if SearchSpecial#SearchWithout(@/, 0, '', 'default', '', v:count1)<Bar>
    \   if &hlsearch<Bar>set hlsearch<Bar>endif<Bar>
    \   else<Bar>echoerr ingo#err#Get()<Bar>endif<CR>
The 'hlsearch' handling cannot be done in a function; and any "Pattern not
found" error is raised directly from the mapping; that's the boilerplate code
at the end of the mapping.
install details
The code is hosted in a Git repo at
You can use your favorite plugin manager, or "git clone" into a directory used
for Vim packages. Releases are on the "stable" branch, the latest unstable
development snapshot on "master".

This script is also 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 SearchSpecial*.vmb.gz
    :so %
To uninstall, use the :RmVimball command.

- Requires Vim 7.0 or higher.
- Requires the ingo-library.vim plugin (vimscript #4433), version 1.019 or

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
SearchSpecial-1.20.vmb.gz 1.20 2017-12-08 7.0 Ingo Karkat - ENH: Extract search {offset} from the last search history element and apply it after jumping if the passed a:searchPattern is also the last element in the history. This can be turned off via a:options.isAutoOffset. The implementation even handles another search (|//;|), even though this is only considered for an initial search, not for subsequent searches (only the last pattern is stored in @/, not the full search sequence).
- a:options.EchoFunction and a:options.ErrorFunction now get supplied a:searchPattern which is either a String of a List of [searchPattern, searchOffset] if such is specified (via a:options.isAutoOffset).
- ENH: Add a:options.searchOffset to allow clients set the search offset.
SearchSpecial-1.10.vmb.gz 1.10 2017-11-19 7.0 Ingo Karkat - ENH: Allow to configure the echoing of successful matches via a:options.EchoFunction.
- ENH: Allow to configure the error messages when there are no matches via a:options.ErrorFunction.
- ENH: Allow to return more search information via a:options.isReturnMoreInfo.
- ENH: Allow to run commands before and after the first search via a:options.BeforeFirstSearchAction and a:options.AfterFirstSearchAction. Needed for SearchManyLocations.vim.
- ENH: Allow to run commands after each search via a:options.AfterAnySearchAction and after the final search jump via a:options.AfterFinalSearchAction. Allow to specify a:options.additionalSearchFlags. Both required for SearchAsQuickJump.vim offset enhancement.
SearchSpecial-1.00.vmb.gz 1.00 2014-05-24 7.0 Ingo Karkat Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github