sponsor Vim development Vim logo Vim Book Ad

CompleteHelper : Generic functions to support custom insert mode completions.

 script karma  Rating 17/5, Downloaded by 1117    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:          Completes any sequence of alphabetic characters.
(vimscript #4912)
BidiComplete:           Considers text before AND AFTER the cursor.
(vimscript #4658)

CamelCaseComplete:      Expands CamelCaseWords and underscore_words based on
(vimscript #3915)       anchor characters for each word fragment.

EntryComplete:          Completes whole lines from designated files or
(vimscript #5073)       buffers.

InnerFragmentComplete:  Completes (and expands CamelCaseWord) fragments inside
(vimscript #4804)       words.

LineComplete:           Completes entire lines with looser matching that the
(vimscript #4911)       built-in i_CTRL-X_CTRL-L.

MotionComplete:         Completes a chunk covered by queried {motion} or text
(vimscript #4265)       object.
    BracketComplete     Completes text inside various brackets.
    (vimscript #4266)

    LineEndComplete     Completes the rest of the line.
    (vimscript #4267)

MultiWordComplete:      Completes a sequence of words based on anchor
(vimscript #4805)       characters for each word.

PatternComplete:        Completes matches of queried {pattern} or last search
(vimscript #4248)       pattern.

PrevInsertComplete:     Recall and insert mode completion for previously
(vimscript #4185)       inserted text.

SameFiletypeComplete:   Completion from buffers with the same filetype.
(vimscript #4242)

SnippetComplete:        Completes defined abbreviations and other snippets.
(vimscript #2926)

SpecialLocationComplete:Completes special, configurable custom patterns.
(vimscript #5120)

- 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
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 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.019 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.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.
SourceForge.net Logo