Home

Creating a source

With nvim-compe, creating a custom source is extremely easy and straight forward thanks to compe#source#vim_bridge#register('source name', dict) function. All you need to create your new custom source is a dict that defines three methods, namely:

• get_metadata,
• datermine and
• complete

Below is an overview of what is expected from each of those methods

Overview

get_metadata

get_metadata must return dict that defines the source's metadata.

The metadata can have one or all of the following fields ...

• dup: 1/0 see :help complete-items
  • This field is used to specify whether to display other items with the same word.
• menu: string see :help complete-items
• priority: number
  • This field is important for nvim-compe's filtering mechanism, the higher the number for displaying top of pum.
• sort: boolean
  • This uses nvim-compe's filtering implementation.
  • The items do not sort so the source should sort items manually.
• filetypes: list
  • This field is useful for filetype specific sources.
  • If this field was specified, nvim-compe will completion on only specified filetypes.

datermine

datermine method must return { keyword_pattern_offset?: number, trigger_character_offset?: number } (it specify the pum position).

If this method doesn't anything, completion will not be triggered.

The keyword_pattern_offset means pum position. In PHP, When the line is $|, keyword_pattern_offset should 1 (it means should include $ as keyword).

complete

The complete method should complete items and callback it.

Examples

In Vim script

function! s:get_metadata(...) abort
  return {
  \   'priority': 10,
  \   'menu': '[MY CUSTOM SOURCE]',
  \ }
endfunction

function! s:datermine(context) abort
  let l:keyword_pattern_offset = compe#pattern#get_keyword_pattern_offset(a:context)
  if l:keyword_pattern_offset > 0
    return {
    \   'keyword_pattern_offset': l:keyword_pattern_offset
    \ }
  endif
  return {}
endfunction

function! s:complete(context) abort
  call a:context.callback({
  \   'items': [
  \     { 'word': 'January' },
  \     { 'word': 'February' },
  \     { 'word': 'March' },
  \     { 'word': 'April' },
  \     { 'word': 'May' },
  \     { 'word': 'June' },
  \     { 'word': 'July' },
  \     { 'word': 'August' },
  \     { 'word': 'September' },
  \     { 'word': 'October' },
  \     { 'word': 'November' },
  \     { 'word': 'December' },
  \   ]
  \ })
endfunction

let s:source = {
\   'get_metadata': function('s:get_metadata'),
\   'datermine': function('s:datermine'),
\   'complete': function('s:complete'),
\ }

" Register your custom source.
call compe#source#vim_bridge#register('month', s:source)

In Lua

The most simple source can be created by the below example of codes.

local local Pattern = require'compe.pattern'

local Source = {}

function Source.new()
  return setmetatable({}, { __index = Source })
end

function Source.get_metadata(self)
  return {
    priority = 10;
    menu = '[MY CUSTOM SOURCE]';
  }
end

function Source.datermine(self, context)
  return {
    keyword_pattern_offset = Pattern:get_keyword_pattern_offset(context)
  }
end

function Source.complete(self, context)
  context.callback({
    items = {
      { word = 'January'; };
      { word = 'February'; };
      { word = 'March'; };
      { word = 'April'; };
      { word = 'May'; };
      { word = 'June'; };
      { word = 'July'; };
      { word = 'August'; };
      { word = 'September'; };
      { word = 'October'; };
      { word = 'November'; };
      { word = 'December'; };
    };
  })

end

-- Register your custom source.
require'compe':register_lua_source('month', Source)

Examples:

• https://github.com/tami5/compe-conjure
• https://github.com/tami5/vim-iced-compe

Q/A

What are the use cases where datermine, Should return an empty object?

• E.g. in the different file type.
• E.g. for invalid line.