Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Generic functions to support custom insert mode completions.
branch: master

Version 1.50

- 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.
latest commit d890cc9924
Ingo Karkat authored committed
Failed to load latest commit information.


This is a mirror of

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)

- Mark Weber's vim-addon-completion library
  ( has some functions to
  switch between completions and to do CamelCase matching.

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, '&#039) . '\k\+', {'complete': '.'} )
            return l:matches

    inoremap <C-x><C-z> <C-o>:set completefunc=SimpleComplete<CR><C-x><C-u>
Something went wrong with that request. Please try again.