From 9d48dd0d5bc900078ebda562430646a51a0faa94 Mon Sep 17 00:00:00 2001 From: hrsh7th Date: Sat, 27 Nov 2021 17:41:48 +0900 Subject: [PATCH] Add documents (#460) * wip * WIP * Update * Update --- doc/cmp.txt | 473 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 473 insertions(+) create mode 100644 doc/cmp.txt diff --git a/doc/cmp.txt b/doc/cmp.txt new file mode 100644 index 0000000..14af912 --- /dev/null +++ b/doc/cmp.txt @@ -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 <'] = cmp.mapping(cmp.mapping.scroll_docs(-4), { 'i', 'c' }), + [''] = cmp.mapping(cmp.mapping.scroll_docs(4), { 'i', 'c' }), + [''] = cmp.mapping(cmp.mapping.complete(), { 'i', 'c' }), + [''] = cmp.mapping({ + i = cmp.mapping.abort(), + c = cmp.mapping.close(), + }), + [''] = 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 `require('cmp').complete()`. + +*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 `` or `(`. +The nvim-cmp will overwrite it but you can fallback to the original mapping via invoking the `fallback` function. +> + cmp.setup { + mapping = { + [''] = 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 = { + [''] = cmp.mapping(your_mapping_function, { 'i', 'c' }) + } + } +< +And you can specify the different mapping function for each modes. +> + cmp.setup { + mapping = { + [''] = 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 = { + [''] = 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 + 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: +