sponsor Vim development Vim logo Vim Book Ad

CompleteHelper : Generic functions to support custom insert mode completions.

 script karma  Rating 29/8, Downloaded by 5765  Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
Via 'completefunc' and the i_CTRL-X_CTRL-U command, it is possible to define
custom complete-functions. To write extensions or alternatives to the
built-in completion functions, you often need to derive the completion
candidates from Vim's buffers and windows. This plugin offers generic
functions around extraction and handling of completion matches (something that
Vim doesn't yet expose to Vimscript), so that building your own custom
completion is quick and simple.

The following custom completions use this plugin:

- AlphaComplete.vim (vimscript #4912):
  Completes any sequence of alphabetic characters.
- BidiComplete.vim (vimscript #4658):
  Considers text before AND AFTER the cursor.
- CamelCaseComplete.vim (vimscript #3915):
  Expands CamelCaseWords and underscore_words based on anchor characters for
  each word fragment.
- EntryComplete.vim (vimscript #5073):
  Completes whole lines from designated files or buffers.
- InnerFragmentComplete.vim (vimscript #4804):
  Completes (and expands CamelCaseWord) fragments inside words.
- LineComplete.vim (vimscript #4911):
  Completes entire lines with looser matching that the built-in
- MotionComplete.vim (vimscript #4265):
  Completes a chunk covered by queried {motion} or text object.
  - BracketComplete.vim (vimscript #4266):
    Completes text inside various brackets.
  - LineEndComplete.vim (vimscript #4267):
    Completes the rest of the line.
- MultiWordComplete.vim (vimscript #4805):
  Completes a sequence of words based on anchor characters for each word.
- PatternComplete.vim (vimscript #4248):
  Completes matches of queried {pattern} or last search pattern.
- PrevInsertComplete.vim (vimscript #4185):
  Recall and insert mode completion for previously inserted text.
- SameFiletypeComplete.vim (vimscript #4242):
  Completion from buffers with the same filetype.
- SnippetComplete.vim (vimscript #2926):
  Completes defined abbreviations and other snippets.
- SpecialLocationComplete.vim (vimscript #5120):
  Completes special, configurable custom patterns.
- WORDComplete.vim (vimscript #5613):
  Completes an entire sequence of non-blank characters.

- Mark Weber's vim-addon-completion library
  (https://github.com/MarcWeber/vim-addon-completion) has some functions to
  switch between completions and to do CamelCase matching.

The options.complete attribute specifies what is searched, like the 'complete'
option for built-in completions. The following (comma-separated) option values
are currently supported:
    - "." current buffer
    - "w" buffers from other windows
    - "b" other loaded buffers that are in the buffer list
    - "u" unloaded buffers that are in the buffer list
    - "U" buffers that are not in the buffer list

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

CompleteHelper#FindMatches( matches, pattern, options )

The main helper function that finds all matches of a:pattern in buffers
specified by a:options, and returns them in the List a:matches that can be
returned as-is to Vim.

CompleteHelper#Find( matches, Funcref, options )

A generic alternative that doesn't prescribe using a regular expression match.
Instead, a Funcref is passed to find and extract matches, reusing the window
and buffer iteration functionality provided by this plugin.

CompleteHelper#ExtractText( startPos, endPos, matchObj )

Low-level function for extracting text from the current buffer. This is the
default extractor used by CompleteHelper#FindMatches().

CompleteHelper#Abbreviate#Word( matchObj )

Processes the match objects to make them prettier to display. Usually
|map()|ed over the matches returned from CompleteHelper#FindMatches().

CompleteHelper#JoinMultiline( text )

Can be used in CompleteHelper#FindMatches()'s a:options.processor if you want
to flatten multi-line matches, as the current default behavior of Vim is not
what users expect. (Newlines are inserted literally as ^@.)


Some built-in completions support the repetition of a completion, so that
subsequent words from the completion source are appended. This function allows
to implement such a repetition for custom completions, too.

To help you with developing your own plugins, you can make the plugin save the
last used pattern(s) in a global variable, if it is defined:
    :let g:CompleteHelper_DebugPatterns = []
    " Trigger custom completion.
    :echo g:CompleteHelper_DebugPatterns

Here is a simple completion that completes the keywords in front of the cursor
from the current file, like the built-in compl-current does. From the
completion base, it constructs a regexp matching all keywords that start with
the base, and delegates the entire work of finding the matches and building
the appropriate match objects to CompleteHelper#FindMatches().
    function! SimpleComplete( findstart, base )
        if a:findstart
            " Locate the start of the keyword.
            let l:startCol = searchpos('\k*\%#', 'bn', line('.'))[1]
            if l:startCol == 0
                let l:startCol = col('.')
            return l:startCol - 1 " Return byte index, not column.
            " Find matches starting with a:base.
            let l:matches = []
            call CompleteHelper#FindMatches( l:matches, '\V\<' . escape(a:base, '') . '\k\+', {'complete': '.'} )
            return l:matches

    inoremap <C-x><C-z> <C-o>:set completefunc=SimpleComplete<CR><C-x><C-u>
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 CompleteHelper*.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.028 or

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

When no a:options.backward_search is passed to CompleteHelper#FindMatches(),
it defaults to backwards search, as this offers recent / preceding matches
(which are likier to be recalled) first. If you don't want that, either
explicitly pass the a:options.backward_search flag (especially do this if you
offer both backward and forward matching mappings), or globally revert to the
previous behavior via:
    let g:CompleteHelper_IsDefaultToBackwardSearch = 0

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
CompleteHelper-1.52.vmb.gz 1.52 2017-09-28 7.0 Ingo Karkat - Need to restore entire view, not just the cursor position when matching in the current window. Else, a completion may change the current view.
- CompleteHelper#Abbreviate#Word(): Only offer the full word in the preview window if a:matchObj.info hasn't been set yet.
- Use ingo#compat#window#IsCmdlineWindow(). *** You need to update to ingo-library (vimscript #4433) version 1.028! ***
CompleteHelper-1.51.vmb.gz 1.51 2015-04-23 7.0 Ingo Karkat - Backwards compatibility: haslocaldir() doesn't exist in Vim 7.0.
- FIX: Duplicate matches when the additional match info is different. Only CompleteHelper#AddMatch() when the same a:match.word doesn't yet exist in a:matches; a test for existence of the same a:match object isn't sufficient due to the other attributes.
- Don't consider the current buffer when a:options.complete does not contain "."; some completions may want to explicitly exclude the current buffer.
- CHG: Exclude unloaded buffers from a:options.complete = "b" and introduce "u" option value for those.
- Add "U" option value for unlisted (loaded and unloaded) buffers, like in the built-in 'complete' option.
- DWIM: Check for a:options.extractor and then skip incompatible a:options.complete values. This allows MotionComplete.vim plugins to default to 'complete' values and prevents user misconfiguration.
- FIX: Also consider buffers from windows visible in other tab pages (by collecting their buffer numbers, not by actually visiting each tab page). This matters when a:options.complete does not contain "b" (or "u" when unlisted buffers are shown in a window).
- ENH: Keep previous (last accessed) window when searching through them for matches.
CompleteHelper-1.50.vmb.gz 1.50 2014-12-23 7.0 Ingo Karkat - Split the match extraction via pattern match from the window / buffer iteration, which now takes a generic Funcref, allowing for other algorithms: Remove ...Matches... from the s:FindMatchesIn...() functions. Extract s:MatchInCurrent() and s:MatchInBuffer(). Add CompleteHelper#Find() generic alternative to CompleteHelper#FindMatches() that takes a Funcref instead of a regular expression.
- Expose CompleteHelper#AddMatch().
- ENH: Add a:options.abbreviate and evaluate in CompleteHelper#AddMatch(). This saves completion plugins from doing an additional map() over the List of matches.
CompleteHelper-1.42.vmb.gz 1.42 2014-11-28 7.0 Ingo Karkat - getbufline() can only access loaded buffers, for completion from unloaded buffers, we need to use readfile().
CompleteHelper-1.41.vmb.gz 1.41 2014-05-31 7.0 Ingo Karkat - FIX: In the completion buffer, check for the cursor position being anywhere in the match, not just at the end. We must not only avoid matching the base, but any text around the cursor. This is especially important for completion repeats, to avoid offering text after the cursor. *** You need to update to ingo-library (vimscript #4433) version 1.019! ***
CompleteHelper-1.40.vmb.gz 1.40 2014-04-16 7.0 Ingo Karkat - Remove the duplicated implementation in CompleteHelper#ExtractText(), deprecate it, and delegate to ingo#text#Get().
- FIX: a:options.backward_search with falsy value also enables backward search.
- Add g:CompleteHelper_IsDefaultToBackwardSearch config var that lets CompleteHelper#FindMatches() default to backwards search when no a:options.backward_search is given. Since all of my custom completions don't offer separate backward / forward mappings, and backward search (i.e. offering first what got recently typed) makes more sense, default to backward search from now on.
- Allow to debug the pattern via :let g:CompleteHelper_DebugPatterns = [].
- Allow completion repeats to continue repeating from following lines like the built-in completions do: The newline plus any indent is removed, and just the first word from the following line is matched. For this, the CompleteHelper#Repeat#Processor() is offered.
- I18N: Correctly handle repeats of (text ending with a) multi-byte character: Instead of just subtracting one from the column, ask for an end-exclusive text grab from ingo#text#Get().
- Add CompleteHelper#Repeat#GetPattern() to encapsulate the common assembly of the repeat pattern, especially the complex expressions with negative and positive character expressions to emulate Vim's built-in completion repeat behavior. *** You need to update to ingo-library (vimscript #4433) version 1.018! ***
CompleteHelper-1.32.vmb.gz 1.32 2013-12-14 7.0 Ingo Karkat - ENH: Allow to pass a List of regular expressions to CompleteHelper#FindMatches(). If you have multiple regular expressions that can match at the same position and should yield separate matches, you cannot use regular expression branches.
- Add dependency to ingo-library (vimscript #4433). *** You need to separately install ingo-library (vimscript #4433) version 1.014 (or higher)! ***
CompleteHelper-1.31.vmb.gz 1.31 2013-03-07 7.0 Ingo Karkat - Truncate to a bit less than half of Vim's width because the popup menu spacing as well as fold, number and sign columns further reduce the available space.
- Avoid "E11: Invalid in command-line window" error when performing completions that search other windows from the command-line window. Use the buffer-search instead; it does not need to change the current window for its search.
- FIX: Don't abort iteration of buffers in s:FindMatchesInOtherBuffers() when one buffer was already searched; instead :continue with the next.
CompleteHelper-1.30.vmb.gz 1.30 2012-09-27 7.0 Ingo Karkat - ENH: Allow skipping of buffers via new a:options.bufferPredicate Funcref.
- Optimization: Skip search in other windows where there's only one that got searched already by s:FindMatchesInCurrentWindow().
- Optimization: Only visit window when its buffer wasn't already searched.
- ENH: Implement a:options.complete = 'b' (only supporting single-line matches and no a:options.extractor).
- Transparently handle 'autochdir': still show the correct relative path in matches from other windows, and restore the buffer's CWD even if it was temporarily changed.
CompleteHelper-1.11.vmb.gz 1.11 2012-09-03 7.0 Ingo Karkat - Make a:matchObj in CompleteHelper#ExtractText() optional; it's not used there, anyway. This avoids having to pass an empty dictionary just to satisfy the API.
- Introduce a:alreadySearchedBuffers to allow for swapped order in a:options.complete and to prepare for additional complete options.

CompleteHelper.vba.gz 1.10 2012-05-05 7.0 Ingo Karkat - Factor out CompleteHelper#Abbreviate#Text() to allow processing of completion menu text (and other uses), too.
- ENH: Offer full completion word in the preview window when it is shown abbreviated. Clients get this automatically when using CompleteHelper#Abbreviate#Word().
CompleteHelper.vba.gz 1.00 2012-01-31 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