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