Repository files navigation

❤️ for my favorite editor

This is afast, extensible, async completion framework forneovim. For more information about pluginimplementation, please read theWhy section.

Future updates, announcements, screenshots will be postedhere.Subscribe it if you are interested.

• Features
• Scoping Sources:
• Completion Sources
• How to extend this framework?
• Requirements
• Installation
• Optional Configuration Tips
• Why?
  • Async architecture
  • Scoping
  • Experimental hacking
• FAQ
  • Why Python?
• Trouble-shooting
• Related Projects

1. Asynchronous completion support like deoplete.
2. Faster, all completions should run in parallel.
3. Smarter on files with different languages, for example, css/javascriptcompletion in html style/script tag.
4. Extensible async vimscript API and python3 API.
5. Function parameter expansion viaUltisnips,neosnippet.vim orvim-snipmate.

• Language specific completion for markdown, reStructuredText
• Javascript code completion in html script tag
• Css code completion in html style tag

• :help ncm-source-examples for minimal examples
• Some real, small examples:github-emoji,nvim-cm-racer

Please announce your new pluginhere afteryou've created the extension.

• For Neovim:
  • echo has("python3")
• For Vim 8:
  • roxma/vim-hug-neovim-rpc
  • g:python3_host_prog pointed to your python3 executable, orecho exepath('python3') is not empty.
  • neovim python client (pip3 install neovim)

• Assuming you're usingvim-plug

" the frameworkPlug'roxma/nvim-completion-manager'

• If you arevim8 user, you'll needvim-hug-neovim-rpc. The vim8support layer is still experimental, please 'upgrade' toneovim if it's possible.

" Requires vim8 with has('python') or has('python3')" Requires the installation of msgpack-python. (pip install msgpack-python)if!has('nvim')    Plug'roxma/vim-hug-neovim-rpc'endif

• Install pip modules for your neovim python3:

# neovim is the required pip module# jedi for python completion# psutil (optional)# setproctitle (optional)pip3 install --user neovim jedi psutil setproctitle

(Optional) It's easier to usepython-support.nvim to helpmanage your pip modules for neovim:

• Supress the annoying completion messages:

" don't give |ins-completion-menu| messages.  For example," '-- XXX completion (YYY)', 'match 1 of 2', 'The only match',setshortmess+=c

• When the<Enter> key is pressed while the popup menu is visible, it onlyhides the menu. Use this mapping to hide the menu and also start a new line.

inoremap<expr><CR>(pumvisible() ? "\<c-y>\<cr>" : "\<CR>")

• Here is an example for expanding snippet in the popup menu with<Enter>key. Suppose you use the<C-U> key for expanding snippet.

imap<expr><CR>(pumvisible() ?  "\<c-y>\<Plug>(expand_or_nl)" : "\<CR>")imap<expr><Plug>(expand_or_nl)(cm#completed_is_snippet() ? "\<C-U>":"\<CR>")

• When usingCTRL-C key to leave insert mode, it does not trigger theautocmdInsertLeave. You should useCTRL-[, or map the<c-c> to<ESC>.

inoremap<c-c><ESC>

• Use<TAB> to select the popup menu:

inoremap<expr><Tab>pumvisible() ? "\<C-n>" : "\<Tab>"inoremap<expr><S-Tab>pumvisible() ? "\<C-p>" : "\<S-Tab>"

• If 'omnifunc' is the only available option, you may register it as a sourcefor NCM.

" css completion via `csscomplete#CompleteCSS`" The `'cm_refresh_patterns'` is PCRE." Be careful with `'scoping': 1` here, not all sources, especially omnifunc," can handle this feature properly.auUserCmSetupcallcm#register_source({'name' :'cm-css',\'priority':9,\'scoping':1,\'scopes': ['css','scss'],\'abbreviation':'css',\'word_pattern':'[\w\-]+',\'cm_refresh_patterns':['[\w\-]+\s*:\s+'],\'cm_refresh': {'omnifunc':'csscomplete#CompleteCSS'},\})

Warning:omnifunc is implemented in a synchronouse style, andvim-vimscript is single threaded, it would potentially block the ui with theintroduction of a heavy weightomnifunc, for example the builtinphpcomplete. If you get some time, please try implementing a source for NCM asa replacement for the old style omnifunc.

• There's no guarantee that this plugin will be compatible with othercompletion plugin in the same buffer. Uselet g:cm_smart_enable=0 andcall cm#enable_for_buffer() to use this plugin for specific buffer.

• This example shows how to disable NCM's builtin tag completion. It's alsopossible to useg:cm_sources_override to override other default options ofa completion source.

letg:cm_sources_override= {\'cm-tags': {'enable':0}\}

This project was started just for fun, and it's working pleasingly for me now.However, it seems there's lots of differences between deoplete, YCM, andnvim-completion-manager, by implementation.

I haven't read the source of YCM yet. So here I'm describing the basicimplementation of NCM (short for nvim-completion-manager) and some of thedifferences between deoplete and this plugin.

Each completion source should be a thread or a standalone process, the managernotifies the completion source for any text changing, even when popup menu isvisible. The completion source notifies the manager if there's any completematches available. After some basic priority sorting between completionsources, and some simple filtering, the completion popup menu will betriggered with thecomplete() function by the completion manager.

If some of the completion source is calculating matches for a long long time,the popup menu will still be shown quickly if other completion sources workproperly. And if the user hasn't changed anything, the popup menu will beupdated after the slow completion source finishes the work.

As the time as of this plugin being created, the completion sources ofdeoplete are gathered withgather_candidates() of theSource object,inside a for loop, in deoplete's process. A slow completion source may deferthe display of popup menu. Of course it will not block the ui.

The good news is that deoplete has supported asyncgather_candidates now.But still, NCM is potentially faster because all completion sources run inparallel.

I write markdown files with code blocks quite often, so I've also implementedlanguage specific completion for markdown file. This is a framework feature,which is called scoping. It should work for any markdown code block whoselanguage completion source is avaible to NCM. I've also added support forjavascript completion in script tag of html files, and css completion in styletag.

The idea was originated invim-syntax-compl-pop. Sinceit's pure vimscript implementation, and there are some limitations currentlywith neovim's syntax api. It's very likely that vim-syntax-compl-pop doesn'twork, for example, javascript completion in markdown or html script tag. So Iuse custom parser in NCM to implement the scoping features.

Note that there's some hacking done in NCM. It uses a per 30ms timer to detectchanges even popup menu is visible, as well as using theTextChangedI event,which only triggers when no popup menu is visible. This is important forimplementing the async architecture. I'm hoping one day neovim will offerbetter option rather than a timer or the limitedTextChangedI.

YouCompleteMe hasgoodexplanation.

Moved towiki

asyncomplete.vim