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

Help page changes. (#952)

Browse Source 
Co-authored-by: alexey <serendipitousdog@protonmail.com>
This commit is contained in:
Uefair
2022-05-02 16:43:24 +00:00
committed by GitHub
parent baa8646c24
commit bb5cac4dce
1 changed files with 111 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
doc/cmp.txt
View File

@@ -17,34 +17,32 @@ Config |cmp-config|
Config Helper |cmp-config-helper|
Develop |cmp-develop|
FAQ |cmp-faq|
==============================================================================
Abstract *cmp-abstract*
This is nvim-cmp's document.
1. This docs uses the type definition notation like `{lsp,cmp,vim}.*`
- You can find it `../lua/cmp/types/init.lua`.
2. The advanced configuration is noted in wiki.
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.
- https://github.com/hrsh7th/nvim-cmp/wiki
==============================================================================
Concept *cmp-concept*
- Full support for LSP completion related capabilities
- Powerful customizability via Lua functions
- Powerful customization abilities via Lua functions
- Smart handling of key mapping
- No flicker
==============================================================================
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 are using `native` completion menu.
3. You can disable the `default` options via specifying `cmp.config.disable` value.
Recommended configuration is written 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.
>
call plug#begin(s:plug_dir)
Plug 'neovim/nvim-lspconfig'
@@ -133,40 +131,39 @@ NOTE:
}
EOF
<
==============================================================================
Function *cmp-function*
NOTE: You can call these functions in mapping via `<Cmd>lua require('cmp').complete()<CR>`.
NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functions in mapping.
*cmp.setup* (config: cmp.ConfigSchema)
Setup global configuration. See configuration option.
Setup global configuration. See configuration options.
*cmp.setup.filetype* (filetype: string, config: cmp.ConfigSchema)
Setup filetype configuration to the specific filetype.
Setup filetype-specific configuration.
*cmp.setup.buffer* (config: cmp.ConfigSchema)
Setup buffer configuration to the current buffer.
Setup configuration for the current buffer.
*cmp.setup.cmdline* (cmdtype: string, config: cmp.ConfigSchema)
Setup cmdline configuration to the specific cmdtype.
Setup cmdline configuration for the specific type of cmd.
See |getcmdtype()|
NOTE: nvim-cmp does not support the `=` cmdtype.
NOTE: nvim-cmp does not support the `=` cmd type.
*cmp.visible* ()
Return the completion menu is visible or not.
Return boolean showing whether the completion menu is visible or not.
*cmp.get_entries* ()
Return current all entries.
Return all current entries.
*cmp.get_selected_entry* ()
Return current selected entry. (contains preselected)
Return current selected entry (contains preselected).
*cmp.get_active_entry* ()
Return current selected entry. (without preselected)
Return current selected entry (without preselected).
*cmp.close* ()
Just close the completion menu.
Close the completion menu.
*cmp.abort* ()
Closes the completion menu and restore the current line to the state when it was started current completion.
@@ -175,15 +172,15 @@ NOTE: You can call these functions in mapping via `<Cmd>lua require('cmp').compl
Select next item.
*cmp.select_prev_item* (option: { behavior = cmp.SelectBehavior })*
Select prev item.
Select previous item.
*cmp.scroll_docs* (delta: number)
Scroll docs if it visible.
Scroll docs if visible.
*cmp.complete* (option: { reason = cmp.ContextReason, config = cmp.ConfigSchema })
Invoke completion.
The following configurations defines the key mapping to invoke only snippet completion.
The following configurations defines the key mapping to show completion only for vsnip snippets.
>
cmp.setup {
mapping = {
@@ -199,10 +196,10 @@ NOTE: You can call these functions in mapping via `<Cmd>lua require('cmp').compl
< >
inoremap <C-S> <Cmd>lua require('cmp').complete({ config = { sources = { { name = 'vsnip' } } } })<CR>
<
NOTE: The `config` means a temporary setting, but the `config.mapping` remains permanent.
NOTE: `config` in that case means a temporary setting, but `config.mapping` remains permanent.
*cmp.complete_common_string* ()
Complete common string as like as shell completion behavior.
Complete common string (reminds shell completion behavior).
>
cmp.setup {
mapping = {
@@ -216,12 +213,12 @@ NOTE: You can call these functions in mapping via `<Cmd>lua require('cmp').compl
}
<
*cmp.confirm* (option: cmp.ConfirmOption, callback: function)
Accept current selected completion item.
If you didn't select any items and specified the `{ select = true }` for
this, nvim-cmp will automatically select the first item.
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.
*cmp.event:on* ('%EVENT_NAME%, callback)
Subscribe nvim-cmp's events below.
Subscribe to nvim-cmp's event. Events are listed below.
- `complete_done`: emit after current completion is done.
- `confirm_done`: emit after confirmation is done.
@@ -229,13 +226,13 @@ NOTE: You can call these functions in mapping via `<Cmd>lua require('cmp').compl
==============================================================================
Mapping *cmp-mapping*
The nvim-cmp's mapping mechanism is complex but flexible and user-friendly.
Nvim-cmp's mapping mechanism is complex but flexible and user-friendly.
You can specify the mapping function that receives the `fallback` function as arguments.
You can specify the mapping function that receives the `fallback` function as argument.
The `fallback` function can be used to call an existing mapping.
For example, typical pair-wise plugins automatically define the mapping for `<CR>` or `(`.
The nvim-cmp might overwrite it via your specified mapping configuration.
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.
>
cmp.setup {
@@ -244,7 +241,7 @@ But you can use existing mapping via invoking the `fallback` function.
if cmp.visible() then
cmp.confirm()
else
fallback() -- If you are using vim-endwise, this fallback function will be behaive as the vim-endwise.
fallback() -- If you use vim-endwise, this fallback will behave as vim-endwise.
end
end
}
@@ -271,7 +268,7 @@ And you can specify the mapping modes.
}
}
<
And you can specify the different mapping function for each modes.
And you can specify different mappings for different modes using the same key.
>
cmp.setup {
mapping = {
@@ -285,88 +282,89 @@ And you can specify the different mapping function for each modes.
You can also use built-in mapping helpers.
*cmp.mapping.close* ()
Same as |cmp.close|
Same as |cmp.close|.
*cmp.mapping.abort* ()
Same as |cmp.abort|
Same as |cmp.abort|.
*cmp.mapping.select_next_item* (option: { behavior = cmp.SelectBehavior })
Same as |cmp.select_next_item|
Same as |cmp.select_next_item|.
*cmp.mapping.select_prev_item* (option: { behavior = cmp.SelectBehavior })
Same as |cmp.select_prev_item|
Same as |cmp.select_prev_item|.
*cmp.mapping.scroll_docs* (delta: number)
Same as |cmp.scroll_docs|
Same as |cmp.scroll_docs|.
*cmp.mapping.complete* (option: cmp.CompleteParams)
Same as |cmp.complete|
Same as |cmp.complete|.
*cmp.mapping.complete_common_string* ()
Same as |cmp.complete_common_string|
Same as |cmp.complete_common_string|.
*cmp.mapping.confirm* (option: cmp.ConfirmOption)
Same as |cmp.confirm|
Same as |cmp.confirm|.
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.
Built-in mapping helpers are only available as a configuration option.
If you want to call 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.
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.
==============================================================================
Highlight *cmp-highlight*
*CmpItemAbbr*
The abbr field's highlight group.
Highlights unmatched characters of each completion field.
*CmpItemAbbrDeprecated*
The abbr field's highlight group that only used for deprecated item.
Highlights unmatched characters of each deprecated completion field.
*CmpItemAbbrMatch*
The matched character's highlight group.
Highlights matched characters of each completion field. Matched characters
must form a substring of a field which share a starting position.
*CmpItemAbbrMatchFuzzy*
The fuzzy matched character's highlight group.
Highlights fuzzy-matched characters of each completion field.
*CmpItemKind*
The kind field's highlight group.
Highlights kind of the field.
NOTE: `kind` is a symbol after each completion option.
*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.
Highlights kind of the field for 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
<
*CmpItemMenu*
The menu field's highlight group.
==============================================================================
Autocmd *cmp-autocmd*
You can create custom autocommands for certain nvim-cmp events by defining
autocommands for the User event with the following patterns.
autocommands for the User event with the following patterns:
*CmpReady*
Invoked when nvim-cmp gets sourced from `plugin/cmp.lua`.
==============================================================================
Config *cmp-config*
You can specify the following configuration option via `cmp.setup { ... }` call.
You can use the following options via `cmp.setup { ... }` .
*cmp-config.enabled*
enabled~
`boolean | fun(): boolean`
You can control nvim-cmp should work or not via this option.
Toggles the plugin on and off.
*cmp-config.preselect*
preselect~
@@ -375,7 +373,7 @@ preselect~
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.
nvim-cmp wouldn't pre-select any items.
*cmp-config.mapping*
mapping~
@@ -385,7 +383,7 @@ mapping~
*cmp-config.snippet.expand*
snippet.expand~
`fun(option: cmp.SnippetExpansionParams)`
The snippet expansion function. You must integrate your snippet engine plugin via this.
The snippet expansion function. That's how cmp interacts with snippet engine.
*cmp-config.completion.keyword_length*
completion.keyword_length~
@@ -400,55 +398,54 @@ completion.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.
The event to trigger autocompletion. If false specified, than completion is
only invoked manually.
*cmp-config.completion.completeopt*
completion.completeopt~
`string`
The vim's completeopt like setting. See 'completeopt'.
Besically, You don't need to modify this.
The vim's completeopt-like setting. See 'completeopt'.
Besically, 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 in LSP spec.
The commitCharacters is defined by LSP spec.
*cmp-config.formatting.fields*
formatting.fields~
`cmp.ItemField[]`
The array of completion menu field to specify the order of them.
The 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 to customize the completion menu appearance. See |complete-items|.
This value also can be used to modify `dup` property.
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`.
*cmp-config.matching.disallow_fuzzy_matching*
matching.disallow_fuzzy_matching~
`boolean`
Specify disallow or allow fuzzy matching.
Whether to allow fuzzy matching.
*cmp-config.matching.disallow_partial_matching*
matching.disallow_partial_matching~
`boolean`
Specify disallow or allow partial matching.
Whether to allow partial matching.
*cmp-config.matching.disallow_prefix_unmatching*
matching.disallow_prefix_unmatching~
`boolean`
Specify disallow or allow prefix unmatching.
Whether to allow prefix unmatching.
*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`.
Each item's original priority (given by its corresponding source) will be
increased by `#sources - (source_index - 1)` and 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)
@@ -462,8 +459,8 @@ sorting.comparators~
*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.
List of the sources and their configurations to use.
Order of the sources matters for sorting order.
*cmp-config.sources[n].name*
sources[n].name~
@@ -473,7 +470,7 @@ sources[n].name~
*cmp-config.sources[n].option*
sources[n].option~
`table`
The source specific custom option that defined by the source.
The specific options defined by the source itself.
*cmp-config.sources[n].keyword_length*
sources[n].keyword_length~
@@ -505,8 +502,8 @@ 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.
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.
>
cmp.setup {
sources = {
@@ -529,25 +526,25 @@ sources[n].group_index~
view~
`{ entries: cmp.EntriesConfig|string }`
Specify the view class to customize appearance.
Currently, the possible configurations are:
Currently available configuration options are:
*cmp-config.window.{completion,documentation}.border*
window.{completion,documentation}.border~
`string | string[] | nil`
Border characters used for the completion popup menu when |experimental.native_menu| is disabled.
See :h |nvim_open_win|.
See |nvim_open_win|.
*cmp-config.window.{completion,documentation}.winhighlight*
window.{completion,documentation}.winhighlight~
`string | cmp.WinhighlightConfig`
Specify the window's winhighlight option.
See :h |nvim_open_win|.
See |nvim_open_win|.
*cmp-config.window.{completion,documentation}.zindex*
window.{completion,documentation}.zindex~
`number`
The completion window's zindex.
See :h |nvim_open_win|.
See |nvim_open_win|.
*cmp-config.window.documentation.max_width*
window.documentation.max_width~
@@ -562,14 +559,12 @@ window.documentation.max_height~
*cmp-config.experimental.ghost_text*
experimental.ghost_text~
`boolean | { hl_group = string }`
The boolean value to enable or disable the ghost_text feature.
Whether to enable the ghost_text feature.
==============================================================================
Config Helper *cmp-config-helper*
You can use the following configuration helpers.
You can use the following configuration helpers:
cmp.config.compare~
@@ -577,32 +572,33 @@ cmp.config.compare~
cmp.config.context~
The `cmp.config.context` can be used to context-aware completion toggling.
The `cmp.config.context` can be used for context-aware completion toggling.
>
cmp.setup {
enabled = function()
-- disable completion if the cursor is `Comment` syntax group.
-- disable completion if the cursor is `Comment` syntax group.
return not cmp.config.context.in_syntax_group('Comment')
end
}
<
*cmp.config.context.in_syntax_group* (group)
You can specify the vim's built-in syntax group.
If you use tree-sitter, You should use `cmp.config.context.in_treesitter_capture` instead.
If you use tree-sitter, you should use `cmp.config.context.in_treesitter_capture` instead.
*cmp.config.context.in_treesitter_capture* (capture)
You can specify the treesitter capture name.
If you don't use `nvim-treesitter`, this helper does not work correctly.
If you don't use `nvim-treesitter`, this helper doesn't work correctly.
cmp.config.mapping~
See |:help cmp-mapping|
See |cmp-mapping|
cmp.config.sources~
*cmp.config.sources* (...sources)
You can specify multiple sources arrays.
The sources are grouped in the order you specify, and the groups are displayed in a fallback, like chain completion.
You can specify multiple source arrays. The sources are grouped in the
order you specify, and the groups are displayed as a fallback, like chain
completion.
>
cmp.setup {
sources = cmp.config.sources({
@@ -615,8 +611,8 @@ cmp.config.sources~
cmp.config.window~
*cmp.config.window.bordered* (option)
Specify some window as `bordered`.
The option is described in the `cmp.ConfigSchema`.
Make window `bordered`.
The option is described in `cmp.ConfigSchema`.
>
cmp.setup {
window = {
@@ -625,20 +621,18 @@ cmp.config.window~
}
}
<
==============================================================================
Develop *cmp-develop*
Create custom source~
NOTE:
1. The `complete` method is required. Others can be ommited.
1. The `complete` method is required. Others can be omitted.
2. The `callback` argument must always be called.
3. You can use only `require('cmp')` in custom source.
4. If the LSP spec was changed, nvim-cmp will follow it without any announcement.
5. You should read ./lua/cmp/types and https://microsoft.github.io/language-server-protocol/specifications/specification-current
6. Please add the `nvim-cmp` topic for github repo.
4. If LSP spec was changed, nvim-cmp would follow it without any announcement.
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.
@@ -706,17 +700,16 @@ You can create custom source like the following example.
---Register custom source to nvim-cmp.
require('cmp').register_source('month', source.new())
<
==============================================================================
FAQ *cmp-faq*
Why does cmp automatically select a particular item? ~
How to disable the preselect feature? ~
The nvim-cmp respects LSP(Language Server Protocol) specification.
The LSP spec defines the `preselect` feature for completion.
Nvim-cmp respects 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 the following.
>
cmp.setup {
preselect = cmp.PreselectMode.None
@@ -771,7 +764,7 @@ How to setup on the specific buffer?~
How to disable documentation window?~
You can specify the following config.
You can use the following config.
>
cmp.setup.filetype({ 'markdown', 'help' }, {
window = {
@@ -782,15 +775,15 @@ How to disable documentation window?~
How to integrate with copilot.vim?~
The copilot.vim and nvim-cmp both have a `key-mapping fallback` mechanism.
Therefore, You should manage those plugins by yourself.
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.
>
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 with nvim-cmp' key-mapping configuration.
>
cmp.setup {
mapping = {
@@ -799,7 +792,7 @@ How to integrate with copilot.vim?~
end)
},
experimental = {
ghost_text = false -- this feature conflict to the copilot.vim's preview.
ghost_text = false -- this feature conflict with copilot.vim's preview.
}
}
<
@@ -807,7 +800,7 @@ How to integrate with copilot.vim?~
How to customize menu appearance?~
You can see the nvim-cmp wiki (https://github.com/hrsh7th/nvim-cmp/wiki).
You can see nvim-cmp wiki (https://github.com/hrsh7th/nvim-cmp/wiki).
==============================================================================
vim:tw=78:ts=2:et:ft=help:norl: