Generic functions to support custom insert mode completions.
Latest commit 576759c Apr 23, 2015 Ingo Karkat committed with Version 1.51
- 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.
Failed to load latest commit information.
autoload Version 1.51 Apr 23, 2015
doc Version 1.51 Apr 24, 2015
README Version 1.51 Apr 24, 2015


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)

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

- Mark Weber's vim-addon-completion library
  ( 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, '&#039) . '\k\+', {'complete': '.'} )
            return l:matches

    inoremap <C-x><C-z> <C-o>:set completefunc=SimpleComplete<CR><C-x><C-u>