hrsh7th
473
doc/cmp.txt
Normal file
473
doc/cmp.txt
Normal file
@@ -0,0 +1,473 @@
|
|||||||
|
*nvim-cmp* *cmp*
|
||||||
|
|
||||||
|
A completion plugin for neovim coded in Lua.
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
CONTENTS *cmp-contents*
|
||||||
|
|
||||||
|
Abstract |cmp-abstract|
|
||||||
|
Concept |cmp-concept|
|
||||||
|
Usage |cmp-usage|
|
||||||
|
Function |cmp-function|
|
||||||
|
Mapping |cmp-mapping|
|
||||||
|
Command |cmp-command|
|
||||||
|
Highlight |cmp-highlight|
|
||||||
|
Autocmd |cmp-autocmd|
|
||||||
|
Config |cmp-config|
|
||||||
|
FAQ |cmp-faq|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Abstract *cmp-abstract*
|
||||||
|
|
||||||
|
This is nvim-cmp's document.
|
||||||
|
|
||||||
|
1. The `cmp` object that appears in this docs is the return value of `require('cmp')`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Concept *cmp-concept*
|
||||||
|
|
||||||
|
- Full support for LSP completion related capabilities
|
||||||
|
- Powerful customizability via Lua functions
|
||||||
|
- Smart handling of key mapping
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Usage *cmp-usage*
|
||||||
|
|
||||||
|
The recommendation configurations are the below.
|
||||||
|
|
||||||
|
NOTE:
|
||||||
|
1. You must setup `snippet.expand` function.
|
||||||
|
2. The `cmp.setup.cmdline` won't work if you specified the `experimental.native_menu` option.
|
||||||
|
3. You can disable the `default` options via specifying `cmp.config.disable` value.
|
||||||
|
>
|
||||||
|
call plug#begin(s:plug_dir)
|
||||||
|
Plug 'neovim/nvim-lspconfig'
|
||||||
|
Plug 'hrsh7th/cmp-nvim-lsp'
|
||||||
|
Plug 'hrsh7th/cmp-buffer'
|
||||||
|
Plug 'hrsh7th/cmp-path'
|
||||||
|
Plug 'hrsh7th/cmp-cmdline'
|
||||||
|
Plug 'hrsh7th/nvim-cmp'
|
||||||
|
|
||||||
|
" For vsnip users.
|
||||||
|
Plug 'hrsh7th/cmp-vsnip'
|
||||||
|
Plug 'hrsh7th/vim-vsnip'
|
||||||
|
|
||||||
|
" For luasnip users.
|
||||||
|
" Plug 'L3MON4D3/LuaSnip'
|
||||||
|
" Plug 'saadparwaiz1/cmp_luasnip'
|
||||||
|
|
||||||
|
" For snippy users.
|
||||||
|
" Plug 'dcampos/nvim-snippy'
|
||||||
|
" Plug 'dcampos/cmp-snippy'
|
||||||
|
|
||||||
|
" For ultisnips users.
|
||||||
|
" Plug 'SirVer/ultisnips'
|
||||||
|
" Plug 'quangnguyen30192/cmp-nvim-ultisnips'
|
||||||
|
|
||||||
|
call plug#end()
|
||||||
|
|
||||||
|
set completeopt=menu,menuone,noselect
|
||||||
|
|
||||||
|
lua <<EOF
|
||||||
|
local cmp = require'cmp'
|
||||||
|
|
||||||
|
-- Global setup.
|
||||||
|
cmp.setup({
|
||||||
|
snippet = {
|
||||||
|
expand = function(args)
|
||||||
|
vim.fn["vsnip#anonymous"](args.body) -- For `vsnip` users.
|
||||||
|
-- require('luasnip').lsp_expand(args.body) -- For `luasnip` users.
|
||||||
|
-- require'snippy'.expand_snippet(args.body) -- For `snippy` users.
|
||||||
|
-- vim.fn["UltiSnips#Anon"](args.body) -- For `ultisnips` users.
|
||||||
|
end,
|
||||||
|
},
|
||||||
|
mapping = {
|
||||||
|
['<C-d>'] = cmp.mapping(cmp.mapping.scroll_docs(-4), { 'i', 'c' }),
|
||||||
|
['<C-f>'] = cmp.mapping(cmp.mapping.scroll_docs(4), { 'i', 'c' }),
|
||||||
|
['<C-Space>'] = cmp.mapping(cmp.mapping.complete(), { 'i', 'c' }),
|
||||||
|
['<C-e>'] = cmp.mapping({
|
||||||
|
i = cmp.mapping.abort(),
|
||||||
|
c = cmp.mapping.close(),
|
||||||
|
}),
|
||||||
|
['<CR>'] = cmp.mapping.confirm({ select = true }),
|
||||||
|
},
|
||||||
|
sources = cmp.config.sources({
|
||||||
|
{ name = 'nvim_lsp' },
|
||||||
|
{ name = 'vsnip' }, -- For vsnip users.
|
||||||
|
-- { name = 'luasnip' }, -- For luasnip users.
|
||||||
|
-- { name = 'snippy' }, -- For snippy users.
|
||||||
|
-- { name = 'ultisnips' }, -- For ultisnips users.
|
||||||
|
}, {
|
||||||
|
{ name = 'buffer' },
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
-- `/` cmdline setup.
|
||||||
|
cmp.setup.cmdline('/', {
|
||||||
|
sources = {
|
||||||
|
{ name = 'buffer' }
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
-- `:` cmdline setup.
|
||||||
|
cmp.setup.cmdline(':', {
|
||||||
|
sources = cmp.config.sources({
|
||||||
|
{ name = 'path' }
|
||||||
|
}, {
|
||||||
|
{ name = 'cmdline' }
|
||||||
|
})
|
||||||
|
})
|
||||||
|
|
||||||
|
-- Setup lspconfig.
|
||||||
|
local capabilities = require('cmp_nvim_lsp').update_capabilities(vim.lsp.protocol.make_client_capabilities())
|
||||||
|
require('lspconfig')[%YOUR_LSP_SERVER%].setup {
|
||||||
|
capabilities = capabilities
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
<
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Function *cmp-function*
|
||||||
|
|
||||||
|
NOTE: You can call these functions in mapping via `<Cmd>require('cmp').complete()<CR>`.
|
||||||
|
|
||||||
|
*cmp.setup* (config: cmp.ConfigSchema)
|
||||||
|
Setup global configuration. See configuration option.
|
||||||
|
|
||||||
|
*cmp.setup.buffer* (config: cmp.ConfigSchema)
|
||||||
|
Setup buffer configuration to the current buffer.
|
||||||
|
|
||||||
|
*cmp.setup.cmdline* (cmdtype: string, config: cmp.ConfigSchema)
|
||||||
|
Setup cmdline configuration to the specific cmdtype.
|
||||||
|
See |getcmetype()|
|
||||||
|
NOTE: nvim-cmp does not support the `=` cmdtype.
|
||||||
|
|
||||||
|
*cmp.visible* ()
|
||||||
|
Return the completion menu is visible or not.
|
||||||
|
|
||||||
|
*cmp.get_selected_entry* ()
|
||||||
|
Return current selected entry. (contains preselected)
|
||||||
|
|
||||||
|
*cmp.get_active_entry* ()
|
||||||
|
Return current selected entry. (without preselected)
|
||||||
|
|
||||||
|
*cmp.close* ()
|
||||||
|
Just close the completion menu.
|
||||||
|
|
||||||
|
*cmp.abort* ()
|
||||||
|
Closes the completion menu and restore the current line to the state when it was started current completion.
|
||||||
|
|
||||||
|
*cmp.select_next_item* (option: { behavior = cmp.SelectBehavior })
|
||||||
|
Select next item.
|
||||||
|
|
||||||
|
*cmp.select_prev_item* (option: { behavior = cmp.SelectBehavior })*
|
||||||
|
Select prev item.
|
||||||
|
|
||||||
|
*cmp.scroll_docs* (delta: number)
|
||||||
|
Scroll docs if it visible.
|
||||||
|
|
||||||
|
*cmp.complete* (option: { reason = cmp.ContextReason })
|
||||||
|
Invoke manual completion.
|
||||||
|
|
||||||
|
*cmp.confirm* (option: cmp.ConfirmOption)
|
||||||
|
Confirm current selected completion item.
|
||||||
|
|
||||||
|
*cmp.event:on* ('%EVENT_NAME%, callback)
|
||||||
|
Subscribe nvim-cmp's events below.
|
||||||
|
|
||||||
|
- `confirm_done`: emit after confirmation is done.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Mapping *cmp-mapping*
|
||||||
|
|
||||||
|
The nvim-cmp's mapping mechanism is complex but flexible and user-friendly.
|
||||||
|
|
||||||
|
You can specify the mapping as function that receives the `fallback` function as arguments.
|
||||||
|
The `fallback` function can be used to call an existing mapping.
|
||||||
|
|
||||||
|
For example, typical pair-wise plugins automatically defines a mapping for `<CR>` or `(`.
|
||||||
|
The nvim-cmp will overwrite it but you can fallback to the original mapping via invoking the `fallback` function.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
mapping = {
|
||||||
|
['<CR>'] = function(fallback)
|
||||||
|
if cmp.visible() then
|
||||||
|
cmp.confirm()
|
||||||
|
else
|
||||||
|
fallback() -- If you are using vim-endwise, this fallback function will be behaive as the vim-endwise.
|
||||||
|
end
|
||||||
|
end
|
||||||
|
}
|
||||||
|
}
|
||||||
|
<
|
||||||
|
And you can specify the mapping modes.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
mapping = {
|
||||||
|
['<CR>'] = cmp.mapping(your_mapping_function, { 'i', 'c' })
|
||||||
|
}
|
||||||
|
}
|
||||||
|
<
|
||||||
|
And you can specify the different mapping function for each modes.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
mapping = {
|
||||||
|
['<CR>'] = cmp.mapping({
|
||||||
|
i = your_mapping_function_a,
|
||||||
|
c = your_mapping_function_b,
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
<
|
||||||
|
You can also use built-in mapping helpers.
|
||||||
|
|
||||||
|
*cmp.mapping.close* ()
|
||||||
|
Close the completion menu.
|
||||||
|
|
||||||
|
*cmp.mapping.abort* ()
|
||||||
|
Closes the completion menu and restore the current line to the state when completion was started.
|
||||||
|
|
||||||
|
*cmp.mapping.select_next_item* (option: { behavior = cmp.SelectBehavior })
|
||||||
|
Select the next completion item. (NOTE: This function can be used with omni completion menu)
|
||||||
|
|
||||||
|
*cmp.mapping.select_prev_item* (option: { behavior = cmp.SelectBehavior })
|
||||||
|
Select the prev completion item. (NOTE: This function can be used with omni completion menu)
|
||||||
|
|
||||||
|
*cmp.mapping.scroll_docs* (delta: number)
|
||||||
|
Scroll the documentation window if it's visible.
|
||||||
|
|
||||||
|
*cmp.mapping.complete* (option: { reason = cmp.ContextReason })
|
||||||
|
Invoke completion.
|
||||||
|
|
||||||
|
*cmp.mapping.confirm* (option: cmp.ConfirmOption)
|
||||||
|
Accept current selected completion item.
|
||||||
|
If you didn't select any items and specified the `{ select = true }`,
|
||||||
|
nvim-cmp will automatically select the first item.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
mapping = {
|
||||||
|
['<CR>'] = cmp.mapping.confirm({ select = true })
|
||||||
|
}
|
||||||
|
}
|
||||||
|
<
|
||||||
|
The built-in mapping helper is only available as a configuration option.
|
||||||
|
If you want to call the nvim-cmp features directly, please use |cmp-function| instead.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Command *cmp-command*
|
||||||
|
|
||||||
|
*CmpStatus*
|
||||||
|
Prints source statuses for the current buffer and states.
|
||||||
|
Sometimes `unknown` source will be printed but it isn't problem. (e.g. `cmp-nvim-lsp`)
|
||||||
|
That the reason is the `cmp-nvim-lsp` will registered on the InsertEnter autocmd.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Highlight *cmp-highlight*
|
||||||
|
|
||||||
|
*CmpItemAbbr*
|
||||||
|
The abbr field's highlight group.
|
||||||
|
|
||||||
|
*CmpItemAbbrDeprecated*
|
||||||
|
The abbr field's highlight group that only used for deprecated item.
|
||||||
|
|
||||||
|
*CmpItemAbbrMatch*
|
||||||
|
The matched character's highlight group.
|
||||||
|
|
||||||
|
*CmpItemAbbrMatchFuzzy*
|
||||||
|
The fuzzy matched character's highlight group.
|
||||||
|
|
||||||
|
*CmpItemKind*
|
||||||
|
The kind field's highlight group.
|
||||||
|
|
||||||
|
*CmpItemKind%KIND_NAME%*
|
||||||
|
The kind field's highlight group for specific `lsp.CompletionItemKind`.
|
||||||
|
If you want to overwrite only the method kind's highlight group, you can do this.
|
||||||
|
>
|
||||||
|
highlight CmpItemKindMethod guibg=NONE guifg=Orange
|
||||||
|
<
|
||||||
|
*CmpItemMenu*
|
||||||
|
The menu field's highlight group.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Autocmd *cmp-autocmd*
|
||||||
|
|
||||||
|
*cmp#ready*
|
||||||
|
Invoke after sourcing the `plugin/cmp.lua`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Config *cmp-config*
|
||||||
|
|
||||||
|
You can specify the following configuration option via `cmp.setup { ... }` call.
|
||||||
|
|
||||||
|
*cmp-config.enabled*
|
||||||
|
enabled~
|
||||||
|
`boolean | fun(): boolean`
|
||||||
|
You can control nvim-cmp should work or not via this option.
|
||||||
|
|
||||||
|
*cmp-config.snippet.expand*
|
||||||
|
preselect~
|
||||||
|
`cmp.PreselectMode`
|
||||||
|
|
||||||
|
1. `cmp.PreselectMode.Item`
|
||||||
|
nvim-cmp will pre-select the item that the source specified.
|
||||||
|
2. `cmp.PreselectMode.None`
|
||||||
|
nvim-cmp wouldn't pre-select any item.
|
||||||
|
|
||||||
|
*cmp-config.mapping*
|
||||||
|
mapping~
|
||||||
|
`table<string, fun(fallback: function)`
|
||||||
|
See |cmp-mapping| section.
|
||||||
|
|
||||||
|
*cmp-config.snippet.expand*
|
||||||
|
snippet.expand~
|
||||||
|
`fun(option: cmp.SnippetExpansionParams)`
|
||||||
|
The snippet expansion function. You must integrate your snippet engine plugin via this.
|
||||||
|
|
||||||
|
*cmp-config.completion.keyword_length*
|
||||||
|
completion.keyword_length~
|
||||||
|
`number`
|
||||||
|
The default number value to trigger auto-completion.
|
||||||
|
|
||||||
|
*cmp-config.completion.keyword_pattern*
|
||||||
|
completion.keyword_pattern~
|
||||||
|
`string`
|
||||||
|
The default keyword pattern.
|
||||||
|
|
||||||
|
*cmp-config.completion.autocomplete*
|
||||||
|
completion.autocomplete~
|
||||||
|
`cmp.TriggerEvent[] | false`
|
||||||
|
The auto-completion trigger events. If you specify this value to false, the
|
||||||
|
nvim-cmp does not completion automatically but you can still use the manual
|
||||||
|
completion though.
|
||||||
|
|
||||||
|
*cmp-config.formatting.format*
|
||||||
|
formatting.format~
|
||||||
|
`fun(entry: cmp.Entry, vim_item: vim.CompletedItem): vim.CompletedItem`
|
||||||
|
The function to customize the completion menu appearance. See |complete-items|.
|
||||||
|
|
||||||
|
*cmp-config.formatting.fields*
|
||||||
|
formatting.fields~
|
||||||
|
`cmp.ItemField[]`
|
||||||
|
The array of completion menu field to specify the order of them.
|
||||||
|
|
||||||
|
*cmp-config.sorting.priority_weight*
|
||||||
|
sorting.priority_weight~
|
||||||
|
`number`
|
||||||
|
Specifically, each item's original priority (given by its corresponding source) will be
|
||||||
|
increased by `#sources - (source_index - 1)` multiplied by `priority_weight`.
|
||||||
|
That is, the final priority is calculated by the following formula:
|
||||||
|
>
|
||||||
|
final_score = orig_score + ((#sources - (source_index - 1)) * sorting.priority_weight)
|
||||||
|
<
|
||||||
|
*cmp-config.sorting.comparators*
|
||||||
|
sorting.comparators~
|
||||||
|
`(fun(entry1: cmp.Entry, entry2: cmp.Entry): boolean | nil)[]`
|
||||||
|
The function to customize the sorting behavior.
|
||||||
|
You can use built-in comparators via `cmp.config.compare.*`.
|
||||||
|
|
||||||
|
*cmp-config.formatting.fields*
|
||||||
|
formatting.fields~
|
||||||
|
`cmp.ItemField[]`
|
||||||
|
The array of completion menu field to specify the order of them.
|
||||||
|
|
||||||
|
*cmp-config.sources*
|
||||||
|
sources~
|
||||||
|
`cmp.SourceConfig[]`
|
||||||
|
Array of the source configuration to use.
|
||||||
|
The order will be used to the completion menu's sort order.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].name*
|
||||||
|
sources[n].name~
|
||||||
|
`string`
|
||||||
|
The source name.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].option*
|
||||||
|
sources[n].option~
|
||||||
|
`table`
|
||||||
|
The source specific custom option that defined by the source.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].keyword_length*
|
||||||
|
sources[n].keyword_length~
|
||||||
|
`number`
|
||||||
|
The source specific keyword length to trigger auto completion.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].keyword_pattern*
|
||||||
|
sources[n].keyword_pattern~
|
||||||
|
`number`
|
||||||
|
The source specific keyword pattern.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].trigger_characters*
|
||||||
|
sources[n].trigger_characters~
|
||||||
|
`string[]`
|
||||||
|
The source specific keyword pattern.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].priority*
|
||||||
|
sources[n].priority~
|
||||||
|
`number`
|
||||||
|
The source specific priority value.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].max_item_count*
|
||||||
|
sources[n].max_item_count~
|
||||||
|
`number`
|
||||||
|
The source specific item count.
|
||||||
|
|
||||||
|
*cmp-config.sources[n].group_index*
|
||||||
|
sources[n].group_index~
|
||||||
|
`number`
|
||||||
|
The source group index.
|
||||||
|
|
||||||
|
For example, You can specify the `buffer` source group index to bigger number
|
||||||
|
if you don't want to see the buffer source items when the nvim-lsp source is available.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
sources = {
|
||||||
|
{ name = 'nvim_lsp', group_index = 1 },
|
||||||
|
{ name = 'buffer', group_index = 2 },
|
||||||
|
}
|
||||||
|
}
|
||||||
|
<
|
||||||
|
You can specify this via the built-in configuration helper like this.
|
||||||
|
>
|
||||||
|
cmp.setup {
|
||||||
|
sources = cmp.config.sources({
|
||||||
|
{ name = 'nvim_lsp' },
|
||||||
|
}, {
|
||||||
|
{ name = 'buffer' },
|
||||||
|
})
|
||||||
|
}
|
||||||
|
<
|
||||||
|
*cmp-config.experimental.ghost_text*
|
||||||
|
experimental.ghost_text~
|
||||||
|
`boolean | { hl_group = string }`
|
||||||
|
The boolean value to enable or disable the ghost_text feature.
|
||||||
|
|
||||||
|
*cmp-config.experimental.native_menu*
|
||||||
|
experimental.native_menu~
|
||||||
|
`boolean`
|
||||||
|
The boolean value to enable or disable the native completion menu.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
FAQ *cmp-faq*
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
vim:tw=78:ts=4:et:ft=help:norl:
|
||||||
|
|
||||||
Reference in New Issue
Block a user