leigh/nvim-cmp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation (#1019)

Browse Source 
Co-authored-by: hrsh7th <629908+hrsh7th@users.noreply.github.com>
This commit is contained in:
Jonas Strittmatter
2022-06-09 09:41:59 +02:00
committed by GitHub
parent ce643c12f1
commit 15c7bf7c0d
2 changed files with 106 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -10,17 +10,14 @@ Readme!
1. There is a Github issue that documents [breaking changes](https://github.com/hrsh7th/nvim-cmp/issues/231) for nvim-cmp. Subscribe to the issue to be notified of upcoming breaking changes.
2. This is my hobby project. You can support me via GitHub sponsors.
3. Bug reports are welcome, but I might not fix if you don't provide a minimal reproduction configuration and steps.
4. The nvim-cmp documents is [here](./doc/cmp.txt).
5. The nvim-cmp is designed for `customization`! It's not designed to `work out of the box`.
3. Bug reports are welcome, but don't expect a fix unless you provide minimal configuration and steps to reproduce your issue.
Concept
====================
- Full support for LSP completion related capabilities
- Powerful customizability via Lua functions
- Smart handling of key mapping
- Smart handling of key mappings
- No flicker
@@ -29,7 +26,7 @@ Setup
### Recommended Configuration
This example configuration uses `vim-plug` as the plugin manager and `vim-vsnip` as snippet plugin.
This example configuration uses `vim-plug` as the plugin manager and `vim-vsnip` as a snippet plugin.
```lua
call plug#begin(s:plug_dir)
@@ -135,12 +132,9 @@ EOF
### Where can I find more completion sources?
- See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources)
- See the [GitHub topic](https://github.com/topics/nvim-cmp).
Have a look at the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources) and the `nvim-cmp` [GitHub topic](https://github.com/topics/nvim-cmp).
### Where can I find advanced configuration examples?
See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki)
See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki).

201
doc/cmp.txt
View File

@@ -24,7 +24,7 @@ This is nvim-cmp's document.
1. This help file uses the type definition notation like `{lsp,cmp,vim}.*`
- You can find it in `../lua/cmp/types/init.lua`.
2. Advanced configuration is described on the wiki.
2. Advanced configuration is described in the wiki.
- https://github.com/hrsh7th/nvim-cmp/wiki
==============================================================================
@@ -32,17 +32,17 @@ Concept *cmp-concept*
- Full support for LSP completion related capabilities
- Powerful customization abilities via Lua functions
- Smart handling of key mapping
- Smart handling of key mappings
- No flicker
==============================================================================
Usage *cmp-usage*
Recommended configuration is written below.
A recommended configuration can be found below.
NOTE:
1. You must provide `snippet.expand` function.
2. `cmp.setup.cmdline` won't work if you use `native` completion menu.
3. You can disable the `default` options via specifying `cmp.config.disable` value.
1. You must provide a `snippet.expand` function.
2. `cmp.setup.cmdline` won't work if you use the `native` completion menu.
3. You can disable the `default` options by specifying `cmp.config.disable` value.
>
call plug#begin(s:plug_dir)
Plug 'neovim/nvim-lspconfig'
@@ -134,7 +134,7 @@ Recommended configuration is written below.
==============================================================================
Function *cmp-function*
NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functions in mapping.
NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functions in a mapping.
*cmp.setup* (config: cmp.ConfigSchema)
Setup global configuration. See configuration options.
@@ -146,41 +146,41 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
Setup configuration for the current buffer.
*cmp.setup.cmdline* (cmdtype: string, config: cmp.ConfigSchema)
Setup cmdline configuration for the specific type of cmd.
See |getcmdtype()|
NOTE: nvim-cmp does not support the `=` cmd type.
Setup cmdline configuration for the specific type of command.
See |getcmdtype()|.
NOTE: nvim-cmp does not support the `=` command type.
*cmp.visible* ()
Return boolean showing whether the completion menu is visible or not.
Return a boolean showing whether the completion menu is visible or not.
*cmp.get_entries* ()
Return all current entries.
*cmp.get_selected_entry* ()
Return current selected entry (contains preselected).
Return currently selected entry (including preselected).
*cmp.get_active_entry* ()
Return current selected entry (without preselected).
Return currently selected entry (excluding preselected).
*cmp.close* ()
Close the completion menu.
*cmp.abort* ()
Closes the completion menu and restore the current line to the state when it was started current completion.
Closes the completion menu and restore the current line to the state before the current completion was started.
*cmp.select_next_item* (option: { behavior = cmp.SelectBehavior })
Select next item.
Select the next item.
*cmp.select_prev_item* (option: { behavior = cmp.SelectBehavior })*
Select previous item.
Select the previous item.
*cmp.scroll_docs* (delta: number)
Scroll docs if visible.
Scroll the documentation window if visible.
*cmp.complete* (option: { reason = cmp.ContextReason, config = cmp.ConfigSchema })
Invoke completion.
The following configurations defines the key mapping to show completion only for vsnip snippets.
The following configuration defines a key mapping to show completion only for vsnip snippets.
>
cmp.setup {
mapping = {
@@ -199,7 +199,7 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
NOTE: `config` in that case means a temporary setting, but `config.mapping` remains permanent.
*cmp.complete_common_string* ()
Complete common string (reminds shell completion behavior).
Complete common string (similar to shell completion behavior).
>
cmp.setup {
mapping = {
@@ -213,11 +213,11 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
}
<
*cmp.confirm* (option: cmp.ConfirmOption, callback: function)
Accepts current selected completion item.
If you didn't select any item and `{ select = true }` is specified for
this, nvim-cmp would automatically select the first item.
Accepts the currently selected completion item.
If you didn't select any item and the option table contains `select = true`,
nvim-cmp will automatically select the first item.
*cmp.event:on* ('%EVENT_NAME%, callback)
*cmp.event:on* (%EVENT_NAME%, callback)
Subscribe to nvim-cmp's event. Events are listed below.
- `complete_done`: emit after current completion is done.
@@ -228,12 +228,12 @@ Mapping *cmp-mapping*
Nvim-cmp's mapping mechanism is complex but flexible and user-friendly.
You can specify the mapping function that receives the `fallback` function as argument.
You can specify a mapping function that receives a `fallback` function as an argument.
The `fallback` function can be used to call an existing mapping.
For example, typical pair-wise plugin automatically defines the mappings for `<CR>` and `(`.
Nvim-cmp might overwrite it via specified mapping.
But you can use existing mapping via invoking the `fallback` function.
For example, typical pair-wise plugins automatically define mappings for `<CR>` and `(`.
Nvim-cmp will overwrite it if you provide a mapping. To call the existing mapping,
you would need to invoke the `fallback` function.
>
cmp.setup {
mapping = {
@@ -241,7 +241,7 @@ But you can use existing mapping via invoking the `fallback` function.
if cmp.visible() then
cmp.confirm()
else
fallback() -- If you use vim-endwise, this fallback will behave as vim-endwise.
fallback() -- If you use vim-endwise, this fallback will behave the same as vim-endwise.
end
end
}
@@ -260,7 +260,7 @@ But you can use existing mapping via invoking the `fallback` function.
}
<
And you can specify the mapping modes.
It is possible to specify the modes the mapping should be active in (`i` = insert mode, `c` = command mode, `s` = select mode):
>
cmp.setup {
mapping = {
@@ -268,7 +268,7 @@ And you can specify the mapping modes.
}
}
<
And you can specify different mappings for different modes using the same key.
You can also specify different mappings for different modes by passing a table:
>
cmp.setup {
mapping = {
@@ -279,7 +279,7 @@ And you can specify different mappings for different modes using the same key.
}
}
<
You can also use built-in mapping helpers.
There are also builtin mapping helper functions you can use:
*cmp.mapping.close* ()
Same as |cmp.close|.
@@ -313,33 +313,33 @@ Command *cmp-command*
*CmpStatus*
Describes statuses and states of sources.
Sometimes `unknown` source will be printed but it isn't problem.
For that reason `cmp-nvim-lsp` registered on the InsertEnter autocmd will
have `unknown` status.
Sometimes `unknown` will be printed - this is expected.
For example, `cmp-nvim-lsp` registers itself on InsertEnter autocommand
so the status will be shown as `unknown` when running the command.
==============================================================================
Highlight *cmp-highlight*
*CmpItemAbbr*
Highlights unmatched characters of each completion field.
Highlight group for unmatched characters of each completion field.
*CmpItemAbbrDeprecated*
Highlights unmatched characters of each deprecated completion field.
Highlight group for unmatched characters of each deprecated completion field.
*CmpItemAbbrMatch*
Highlights matched characters of each completion field. Matched characters
Highlight group for matched characters of each completion field. Matched characters
must form a substring of a field which share a starting position.
*CmpItemAbbrMatchFuzzy*
Highlights fuzzy-matched characters of each completion field.
Highlight group for fuzzy-matched characters of each completion field.
*CmpItemKind*
Highlights kind of the field.
Highlight group for the kind of the field.
NOTE: `kind` is a symbol after each completion option.
*CmpItemKind%KIND_NAME%*
Highlights kind of the field for specific `lsp.CompletionItemKind`.
Highlight group for the kind of the field for a specific `lsp.CompletionItemKind`.
If you only want to overwrite the `method` kind's highlight group, you can do this:
>
highlight CmpItemKindMethod guibg=NONE guifg=Orange
@@ -371,9 +371,9 @@ preselect~
`cmp.PreselectMode`
1. `cmp.PreselectMode.Item`
nvim-cmp will pre-select the item that the source specified.
nvim-cmp will preselect the item that the source specified.
2. `cmp.PreselectMode.None`
nvim-cmp wouldn't pre-select any items.
nvim-cmp will not preselect any items.
*cmp-config.mapping*
mapping~
@@ -383,7 +383,8 @@ mapping~
*cmp-config.snippet.expand*
snippet.expand~
`fun(option: cmp.SnippetExpansionParams)`
The snippet expansion function. That's how cmp interacts with snippet engine.
The snippet expansion function. That's how nvim-cmp interacts with a
particular snippet engine.
*cmp-config.completion.keyword_length*
completion.keyword_length~
@@ -398,33 +399,33 @@ completion.keyword_pattern~
*cmp-config.completion.autocomplete*
completion.autocomplete~
`cmp.TriggerEvent[] | false`
The event to trigger autocompletion. If false specified, than completion is
only invoked manually.
The event to trigger autocompletion. If set to `false`, then completion is
only invoked manually (e.g. by calling `cmp.complete`).
*cmp-config.completion.completeopt*
completion.completeopt~
`string`
The vim's completeopt-like setting. See 'completeopt'.
Besically, you don't need to change this.
Like vim's completeopt setting. See 'completeopt'.
In general, you don't need to change this.
*cmp-config.confirmation.get_commit_characters*
confirmation.get_commit_characters~
`fun(commit_characters:string[]):string[]`
You can append or exclude commitCharacters via this configuration option function.
The commitCharacters is defined by LSP spec.
You can append or exclude commitCharacters via this configuration option
function. The commitCharacters are defined by the LSP spec.
*cmp-config.formatting.fields*
formatting.fields~
`cmp.ItemField[]`
The array of completion fields to specify their order.
An array of completion fields to specify their order.
*cmp-config.formatting.format*
formatting.format~
`fun(entry: cmp.Entry, vim_item: vim.CompletedItem): vim.CompletedItem`
The function used to customize the completion menu appearance. See
|complete-items|. This value can also be used to modify `dup` property.
NOTE: The `vim.CompletedItem` can have special properties `abbr_hl_group`,
`kind_hl_group` and `menu_hl_group`.
The function used to customize the appearance of the completion menu. See
|complete-items|. This value can also be used to modify the `dup` property.
NOTE: The `vim.CompletedItem` can contain the special properties
`abbr_hl_group`, `kind_hl_group` and `menu_hl_group`.
*cmp-config.matching.disallow_fuzzy_matching*
matching.disallow_fuzzy_matching~
@@ -460,50 +461,50 @@ sorting.comparators~
sources~
`cmp.SourceConfig[]`
List of the sources and their configurations to use.
Order of the sources matters for sorting order.
The order of the sources determines their order in the completion results.
*cmp-config.sources[n].name*
sources[n].name~
`string`
The source name.
The name of the source.
*cmp-config.sources[n].option*
sources[n].option~
`table`
The specific options defined by the source itself.
Any specific options defined by the source itself.
*cmp-config.sources[n].keyword_length*
sources[n].keyword_length~
`number`
The source specific keyword length to trigger auto completion.
The source-specific keyword length to trigger auto completion.
*cmp-config.sources[n].keyword_pattern*
sources[n].keyword_pattern~
`string`
The source specific keyword pattern.
The source-specific keyword pattern.
*cmp-config.sources[n].trigger_characters*
sources[n].trigger_characters~
`string[]`
The source specific keyword pattern.
A source-specific keyword pattern.
*cmp-config.sources[n].priority*
sources[n].priority~
`number`
The source specific priority value.
The source-specific priority value.
*cmp-config.sources[n].max_item_count*
sources[n].max_item_count~
`number`
The source specific item count.
The source-specific item count.
*cmp-config.sources[n].group_index*
sources[n].group_index~
`number`
The source group index.
For instance, you can specify the `buffer`'s source `group_index` to bigger number
if you don't want to see the buffer source items when nvim-lsp source is available.
For instance, you can set the `buffer`'s source `group_index` to a larger number
if you don't want to see `buffer` source items while `nvim-lsp` source is available:
>
cmp.setup {
sources = {
@@ -512,7 +513,7 @@ sources[n].group_index~
}
}
<
You can specify this via the built-in configuration helper like this.
You can also achieve this by using the built-in configuration helper like this:
>
cmp.setup {
sources = cmp.config.sources({
@@ -525,7 +526,7 @@ sources[n].group_index~
*cmp-config.view*
view~
`{ entries: cmp.EntriesConfig|string }`
Specify the view class to customize appearance.
The view class used to customize nvim-cmp's appearance.
Currently available configuration options are:
*cmp-config.window.{completion,documentation}.border*
@@ -587,11 +588,11 @@ cmp.config.context~
*cmp.config.context.in_treesitter_capture* (capture)
You can specify the treesitter capture name.
If you don't use `nvim-treesitter`, this helper doesn't work correctly.
If you don't use the `nvim-treesitter` plugin, this helper will not work correctly.
cmp.config.mapping~
See |cmp-mapping|
See |cmp-mapping|.
cmp.config.sources~
@@ -611,7 +612,7 @@ cmp.config.sources~
cmp.config.window~
*cmp.config.window.bordered* (option)
Make window `bordered`.
Make the completion window `bordered`.
The option is described in `cmp.ConfigSchema`.
>
cmp.setup {
@@ -624,46 +625,46 @@ cmp.config.window~
==============================================================================
Develop *cmp-develop*
Create custom source~
Creating a custom source~
NOTE:
1. The `complete` method is required. Others can be omitted.
2. The `callback` argument must always be called.
2. The `callback` function must always be called.
3. You can use only `require('cmp')` in custom source.
4. If LSP spec was changed, nvim-cmp would follow it without any announcement.
4. If the LSP spec was changed, nvim-cmp may implement it without any announcement (potentially introducing breaking changes).
5. You should read ./lua/cmp/types and https://microsoft.github.io/language-server-protocol/specifications/specification-current.
6. Please add `nvim-cmp` topic for github repo.
You can create custom source like the following example.
6. Please add your source to the list of sources in the Wiki (https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources)
and if you publish it on GitHub, add the `nvim-cmp` topic so users can find it more easily.
Here is an example on how to create a custom source:
>
local source = {}
---Return this source is available in current context or not. (Optional)
---Return whether this source is available in the current context or not (optional).
---@return boolean
function source:is_available()
return true
end
---Return the debug name of this source. (Optional)
---Return the debug name of this source (optional).
---@return string
function source:get_debug_name()
return 'debug name'
end
---Return keyword pattern for triggering completion. (Optional)
---If this is ommited, nvim-cmp will use default keyword pattern. See |cmp-config.completion.keyword_pattern|
---Return the keyword pattern for triggering completion (optional).
---If this is ommited, nvim-cmp will use a default keyword pattern. See |cmp-config.completion.keyword_pattern|.
---@return string
function source:get_keyword_pattern()
return [[\k\+]]
end
---Return trigger characters for triggering completion. (Optional)
---Return trigger characters for triggering completion (optional).
function source:get_trigger_characters()
return { '.' }
end
---Invoke completion. (Required)
---Invoke completion (required).
---@param params cmp.SourceCompletionApiParams
---@param callback fun(response: lsp.CompletionResponse|nil)
function source:complete(params, callback)
@@ -683,21 +684,22 @@ You can create custom source like the following example.
})
end
---Resolve completion item. (Optional)
---Resolve completion item (optional). This is called right before the completion is about to be displayed.
---Useful for setting the text shown in the documentation window (`completion_item.documentation`).
---@param completion_item lsp.CompletionItem
---@param callback fun(completion_item: lsp.CompletionItem|nil)
function source:resolve(completion_item, callback)
callback(completion_item)
end
---Execute command after item was accepted.
---Executed after the item was selected.
---@param completion_item lsp.CompletionItem
---@param callback fun(completion_item: lsp.CompletionItem|nil)
function source:execute(completion_item, callback)
callback(completion_item)
end
---Register custom source to nvim-cmp.
---Register your source to nvim-cmp.
require('cmp').register_source('month', source.new())
<
==============================================================================
@@ -706,20 +708,19 @@ FAQ *cmp-faq*
Why does cmp automatically select a particular item? ~
How to disable the preselect feature? ~
Nvim-cmp respects LSP(Language Server Protocol) specification.
Nvim-cmp respects the LSP (Language Server Protocol) specification.
The LSP spec defines the `preselect` feature for completion.
You can disable the `preselect` feature like the following.
You can disable the `preselect` feature like this:
>
cmp.setup {
preselect = cmp.PreselectMode.None
}
<
Why nvim-cmp confirm item automatically?~
How to disable commitCharacters?~
You can disable commitCharacters feature (that defined in LSP spec).
You can disable the commitCharacters feature (which is defined in LSP spec):
>
cmp.setup {
confirmation = {
@@ -732,9 +733,9 @@ How to disable commitCharacters?~
How to disable auto-completion?~
How to use nvim-cmp as like omnifunc?~
How to use nvim-cmp as omnifunc?~
You can disable auto-completion like this.
You can disable auto-completion like this:
>
cmp.setup {
...
@@ -744,15 +745,15 @@ How to use nvim-cmp as like omnifunc?~
...
}
<
And you can invoke completion manually.
Then you will need to nvoke completion manually.
>
inoremap <C-x><C-o> <Cmd>lua require('cmp').complete()<CR>
<
How to disable nvim-cmp on the specific buffer?~
How to setup on the specific buffer?~
How to disable nvim-cmp for a specific buffer?~
How to setup nvim-cmp for a specific buffer?~
You can setup buffer specific configuration like this.
You can setup buffer-specific configuration like this:
>
cmp.setup.filetype({ 'markdown', 'help' }, {
sources = {
@@ -762,9 +763,9 @@ How to setup on the specific buffer?~
})
<
How to disable documentation window?~
How to disable the documentation window?~
You can use the following config.
Simply use the following config:
>
cmp.setup.filetype({ 'markdown', 'help' }, {
window = {
@@ -778,12 +779,12 @@ How to integrate with copilot.vim?~
Copilot.vim and nvim-cmp both have a `key-mapping fallback` mechanism.
Therefore, you should manage those plugins by yourself.
Fortunately, the copilot.vim has the feature that disables the fallback mechanism.
Fortunately, the copilot.vim has a feature that disables the fallback mechanism.
>
let g:copilot_no_tab_map = v:true
imap <expr> <Plug>(vimrc:copilot-dummy-map) copilot#Accept("\<Tab>")
<
You can manage copilot.vim's accept feature with nvim-cmp' key-mapping configuration.
You can manage copilot.vim's accept feature inside nvim-cmp's key-mapping function:
>
cmp.setup {
mapping = {
@@ -798,9 +799,9 @@ How to integrate with copilot.vim?~
<
How to customize menu appearance?~
How to customize the menu appearance?~
You can see nvim-cmp wiki (https://github.com/hrsh7th/nvim-cmp/wiki).
Have a look at the wiki (https://github.com/hrsh7th/nvim-cmp/wiki).
==============================================================================
vim:tw=78:ts=2:et:ft=help:norl: