nvim-cmp/doc/cmp.txt

*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|
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.
  - https://github.com/hrsh7th/nvim-cmp/wiki

==============================================================================
Concept                                                            *cmp-concept*

- Full support for LSP completion related capabilities
- Powerful customizability 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.
>
  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,
      },
      window = {
        -- completion = cmp.config.window.bordered(),
        -- documentation = cmp.config.window.bordered(),
      },
      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(),
        }),
        -- Accept currently selected item. If none selected, `select` first item.
        -- Set `select` to `false` to only confirm explicitly selected items.
        ['<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>lua require('cmp').complete()<CR>`.

*cmp.setup* (config: cmp.ConfigSchema)
  Setup global configuration. See configuration option.

*cmp.setup.filetype* (filetype: string, config: cmp.ConfigSchema)
  Setup filetype configuration to the specific filetype.

*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 |getcmdtype()|
  NOTE: nvim-cmp does not support the `=` cmdtype.

*cmp.visible* ()
  Return the completion menu is visible or not.

*cmp.get_entries* ()
  Return current all entries.

*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, config = cmp.ConfigSchema })
  Invoke completion.

  The following configurations defines the key mapping to invoke only snippet completion.
>
  cmp.setup {
    mapping = {
      ['<C-s>'] = cmp.mapping.complete({
        config = {
          sources = {
            { name = 'vsnip' }
          }
        }
      })
    }
  }
< >
  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.

*cmp.complete_common_string* ()
  Complete common string as like as shell completion behavior.
>
  cmp.setup {
    mapping = {
      ['<C-l>'] = cmp.mapping(function(fallback)
        if cmp.visible() then
          return cmp.complete_common_string()
        end
        fallback()
      end, { 'i', 'c' }),
    }
  }
<
*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.

*cmp.event:on* ('%EVENT_NAME%, callback)
  Subscribe nvim-cmp's events below.

  - `complete_done`: emit after current completion is done.
  - `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* ()
    Same as |cmp.close|

  *cmp.mapping.abort* ()
    Same as |cmp.abort|

  *cmp.mapping.select_next_item* (option: { behavior = cmp.SelectBehavior })
    Same as |cmp.select_next_item|

  *cmp.mapping.select_prev_item* (option: { behavior = cmp.SelectBehavior })
    Same as |cmp.select_prev_item|

  *cmp.mapping.scroll_docs* (delta: number)
    Same as |cmp.scroll_docs|

  *cmp.mapping.complete* (option: cmp.CompleteParams)
    Same as |cmp.complete|

  *cmp.mapping.complete_common_string* ()
    Same as |cmp.complete_common_string|

  *cmp.mapping.confirm* (option: cmp.ConfirmOption)
    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.

==============================================================================
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*

You can create custom autocommands for certain nvim-cmp events by defining
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.

                                                            *cmp-config.enabled*
enabled~
  `boolean | fun(): boolean`
  You can control nvim-cmp should work or not via this option.

                                                          *cmp-config.preselect*
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 number of characters needed 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.completion.completeopt*
completion.completeopt~
  `string`
  The vim's completeopt like setting. See 'completeopt'.
  Besically, You don't need to modify this.

                                                  *cmp-config.formatting.fields*
formatting.fields~
  `cmp.ItemField[]`
  The array of completion menu field to specify the order of them.

                                                  *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.
  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.

                                 *cmp-config.matching.disallow_partial_matching*
matching.disallow_partial_matching~
  `boolean`
  Specify disallow or allow partial matching.

                                *cmp-config.matching.disallow_prefix_unmatching*
matching.disallow_prefix_unmatching~
  `boolean`
  Specify disallow or 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`.
  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.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.view*
view~
  `{ entries: cmp.EntriesConfig|string }`
  Specify the view class to customize appearance.
  Currently, the possible configurations 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.

                     *cmp-config.window.{completion,documentation}.winhighlight*
window.{completion,documentation}.winhighlight~
  `string | cmp.WinhighlightConfig`
  Specify the window's winhighlight option.

                           *cmp-config.window.{completion,documentation}.zindex*
window.{completion,documentation}.zindex~
  `number`
  The completion window's zindex.

                                     *cmp-config.window.documentation.max_width*
window.documentation.max_width~
  `number`
  The documentation window's max width.

                                    *cmp-config.window.documentation.max_height*
window.documentation.max_height~
  `number`
  The documentation window's 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.



==============================================================================
Config Helper                                                *cmp-config-helper*

You can use the following configuration helpers.

cmp.config.compare~

  TBD

cmp.config.context~

  The `cmp.config.context` can be used to context-aware completion toggling. 
>
    cmp.setup {
      enabled = function()
        -- 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. 

  *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.

cmp.config.mapping~

  See |:help 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.
>
    cmp.setup {
      window = {
        completion = cmp.config.window.bordered(),
        documentation = cmp.config.window.bordered(),
      }
    }
<
cmp.config.window~

  *cmp.config.window.bordered* (option)
    Specify some window as `bordered`.
    The option is described in the `cmp.ConfigSchema`.
>
    cmp.setup {
      window = {
        completion = cmp.config.window.bordered(),
        documentation = cmp.config.window.bordered(),
      }
    }
<


==============================================================================
Develop                                                            *cmp-develop*

Create custom source~

NOTE:
  1. The `complete` method is required. Others can be ommited.
  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.

You can create custom source like the following example.

>
  local source = {}

  ---Return this source is available in current context or not. (Optional)
  ---@return boolean
  function source:is_available()
    return true
  end

  ---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 string
  function source:get_keyword_pattern()
    return [[\k\+]]
  end

  ---Return trigger characters for triggering completion. (Optional)
  function source:get_trigger_characters()
    return { '.' }
  end

  ---Invoke completion. (Required)
  ---@param params cmp.SourceCompletionApiParams
  ---@param callback fun(response: lsp.CompletionResponse|nil)
  function source:complete(params, callback)
    callback({
      { label = 'January' },
      { label = 'February' },
      { label = 'March' },
      { label = 'April' },
      { label = 'May' },
      { label = 'June' },
      { label = 'July' },
      { label = 'August' },
      { label = 'September' },
      { label = 'October' },
      { label = 'November' },
      { label = 'December' },
    })
  end

  ---Resolve completion item. (Optional)
  ---@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.
  ---@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.
  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. 

  You can disable the `preselect` feature like the following. 
>
  cmp.setup {
    preselect = cmp.PreselectMode.None
  }
<

How to disable auto-completion?~
How to use nvim-cmp as like omnifunc?~

  You can disable auto-completion like this.
>
  cmp.setup {
    ...
    completion = {
      autocomplete = false
    }
    ...
  }
<
  And you can invoke 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?~

  You can setup buffer specific configuration like this.
>
  cmp.setup.filetype({ 'markdown', 'help' }, {
    sources = {
      { name = 'path' },
      { name = 'buffer' },
    }
  })
<

How to disable documentation window?~

  You can specify the following config.
>
  cmp.setup.filetype({ 'markdown', 'help' }, {
    window = {
      documentation = cmp.config.disable
    }
  })
<

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.

  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. 
>
  cmp.setup {
    mapping = {
      ['<C-g>'] = cmp.mapping(function(fallback)
        vim.api.nvim_feedkeys(vim.fn['copilot#Accept'](vim.api.nvim_replace_termcodes('<Tab>', true, true, true)), 'n', true)
      end)
    },
    experimental = {
      ghost_text = false -- this feature conflict to the copilot.vim's preview.
    }
  }
<


How to customize menu appearance?~

  You can see the nvim-cmp wiki (https://github.com/hrsh7th/nvim-cmp/wiki).

==============================================================================
 vim:tw=78:ts=2:et:ft=help:norl: