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

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

- Full support for LSP completion related capabilities
- Powerful customization abilities via Lua functions
- Smart handling of key mappings
- No flicker

==============================================================================
Usage                                                                *cmp-usage*

A recommended configuration can be found below.
  NOTE:
    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'
  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 = cmp.mapping.preset.insert({
        ['<C-d>'] = cmp.mapping.scroll_docs(-4),
        ['<C-f>'] = cmp.mapping.scroll_docs(4),
        ['<C-Space>'] = cmp.mapping.complete(),
        ['<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('/', {
      mapping = cmp.mapping.preset.cmdline(),
      sources = {
        { name = 'buffer' }
      }
    })

    -- `:` cmdline setup.
    cmp.setup.cmdline(':', {
      mapping = cmp.mapping.preset.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: `<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.

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

*cmp.setup.buffer* (config: cmp.ConfigSchema)
  Setup configuration for the current buffer.

*cmp.setup.cmdline* (cmdtype: string, config: cmp.ConfigSchema)
  Setup cmdline configuration for the specific type of command.
  See |getcmdtype()|.
  NOTE: nvim-cmp does not support the `=` command type.

*cmp.visible* ()
  Return a boolean showing whether the completion menu is visible or not.

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

*cmp.get_selected_entry* ()
  Return currently selected entry (including preselected).

*cmp.get_active_entry* ()
  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 before the current completion was started.

*cmp.select_next_item* (option: { behavior = cmp.SelectBehavior })
  Select the next item.

*cmp.select_prev_item* (option: { behavior = cmp.SelectBehavior })*
  Select the previous item.

*cmp.scroll_docs* (delta: number)
  Scroll the documentation window if visible.

*cmp.complete* (option: { reason = cmp.ContextReason, config = cmp.ConfigSchema })
  Invoke completion.

  The following configuration defines a key mapping to show completion only for vsnip snippets.
>
  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: `config` in that case means a temporary setting, but `config.mapping` remains permanent.

*cmp.complete_common_string* ()
  Complete common string (similar to 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)
  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)
  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.
  - `menu_opened`: emit after opening a new completion menu. Called with a table holding a key
    named `window`, pointing to the completion menu implementation.
  - `menu_closed`: emit after completion menu is closed. Called with a table holding a key
    named `window`, pointing to the completion menu implementation.

==============================================================================
Mapping                                                            *cmp-mapping*

Nvim-cmp's mapping mechanism is complex but flexible and user-friendly.

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 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 = {
      ['<CR>'] = function(fallback)
        if cmp.visible() then
          cmp.confirm()
        else
          fallback() -- If you use vim-endwise, this fallback will behave the same as vim-endwise.
        end
      end
    }
  }
< >
  cmp.setup {
    mapping = {
      ['<Tab>'] = function(fallback)
        if cmp.visible() then
          cmp.select_next_item()
        else
          fallback()
        end
      end
    }
  }
<

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 = {
      ['<CR>'] = cmp.mapping(your_mapping_function, { 'i', 'c' })
    }
  }
<
You can also specify different mappings for different modes by passing a table:
>
  cmp.setup {
    mapping = {
      ['<CR>'] = cmp.mapping({
        i = your_mapping_function_a,
        c = your_mapping_function_b,
      })
    }
  }
<
There are also builtin mapping helper functions you can use:

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

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*
  Describes statuses and states of sources.
  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*
  Highlight group for unmatched characters of each completion field.

*CmpItemAbbrDeprecated*
  Highlight group for unmatched characters of each deprecated completion field.

*CmpItemAbbrMatch*
  Highlight group for matched characters of each completion field. Matched characters
  must form a substring of a field which share a starting position.

*CmpItemAbbrMatchFuzzy*
  Highlight group for fuzzy-matched characters of each completion field.

*CmpItemKind*
  Highlight group for the kind of the field.

NOTE: `kind` is a symbol after each completion option.

*CmpItemKind%KIND_NAME%*
  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
<
*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 use the following options via `cmp.setup { ... }` .

                                                            *cmp-config.enabled*
enabled~
  `boolean | fun(): boolean`
  Toggles the plugin on and off.

                                                *cmp-config.performance.debounce*
performance.debounce~
  `number`
  Sets debounce time
  This is the interval used to group up completions from different sources
  for filtering and displaying.

                                                *cmp-config.performance.throttle*
performance.throttle~
  `number`
  Sets throttle time
  This is used to delay filtering and displaying completions.

                                        *cmp-config.performance.fetching_timeout*
  performance.fetching_timeout~
    `number`
    Sets the timeout of candidate fetching process.
    The nvim-cmp will wait to display the most prioritized source.

                                                          *cmp-config.preselect*
preselect~
  `cmp.PreselectMode`

  1. `cmp.PreselectMode.Item`
    nvim-cmp will preselect the item that the source specified.
  2. `cmp.PreselectMode.None`
    nvim-cmp will not preselect any items.

                                                            *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. That's how nvim-cmp interacts with a
  particular snippet engine.

                                          *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 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`
  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 are defined by the LSP spec.

                                                  *cmp-config.formatting.fields*
formatting.fields~
  `cmp.ItemField[]`
  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 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~
  `boolean`
  Whether to allow fuzzy matching.

                                 *cmp-config.matching.disallow_partial_matching*
matching.disallow_partial_matching~
  `boolean`
  Whether to allow partial matching.

                                *cmp-config.matching.disallow_prefix_unmatching*
matching.disallow_prefix_unmatching~
  `boolean`
  Whether to allow prefix unmatching.

                                            *cmp-config.sorting.priority_weight*
sorting.priority_weight~
  `number`
  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)
<
                                                *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[]`
  List of the sources and their configurations to use.
  The order of the sources determines their order in the completion results.

                                                    *cmp-config.sources[n].name*
sources[n].name~
  `string`
  The name of the source.

                                                  *cmp-config.sources[n].option*
sources[n].option~
  `table`
  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.

                                         *cmp-config.sources[n].keyword_pattern*
sources[n].keyword_pattern~
  `string`
  The source-specific keyword pattern.

                                      *cmp-config.sources[n].trigger_characters*
sources[n].trigger_characters~
  `string[]`
  A 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 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 = {
        { name = 'nvim_lsp', group_index = 1 },
        { name = 'buffer', group_index = 2 },
      }
    }
<
  You can also achieve this by using 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 }`
  The view class used to customize nvim-cmp's appearance.
  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 |nvim_open_win|.

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

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

                                       *cmp-config.window.completion.col_offset*
window.completion.col_offset~
  `number`
  Offsets the completion window relative to the cursor.

                                     *cmp-config.window.completion.side_padding*
window.completion.side_padding~
  `number`
  The ammount of padding to add on the completion window's sides

                                     *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 }`
  Whether to enable 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 for 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 the `nvim-treesitter` plugin, this helper will not work correctly.

cmp.config.mapping~

  See |cmp-mapping|.

cmp.config.sources~

  *cmp.config.sources* (...sources)
    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({
        { name = 'nvim_lsp' },
      }, {
        { name = 'buffer' },
      })
    }
<
cmp.config.window~

  *cmp.config.window.bordered* (option)
    Make the completion window `bordered`.
    The option is described in `cmp.ConfigSchema`.
>
    cmp.setup {
      window = {
        completion = cmp.config.window.bordered(),
        documentation = cmp.config.window.bordered(),
      }
    }
<
==============================================================================
Develop                                                            *cmp-develop*

Creating a custom source~

NOTE:
  1. The `complete` method is required. Others can be omitted.
  2. The `callback` function must always be called.
  3. You can use only `require('cmp')` in custom source.
  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 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 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 string
  function source:get_debug_name()
    return 'debug name'
  end

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

  ---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 your 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? ~

  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 this:
>
  cmp.setup {
    preselect = cmp.PreselectMode.None
  }
<

How to disable commitCharacters?~

  You can disable the commitCharacters feature (which is defined in LSP spec):
>
  cmp.setup {
    confirmation = {
      get_commit_characters = function(commit_characters)
        return {}
      end
    }
  }
<


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

  You can disable auto-completion like this:
>
  cmp.setup {
    ...
    completion = {
      autocomplete = false
    }
    ...
  }
<
  Then you will need to invoke completion manually.
>
  inoremap <C-x><C-o> <Cmd>lua require('cmp').complete()<CR>
<

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:
>
  cmp.setup.filetype({ 'markdown', 'help' }, {
    sources = {
      { name = 'path' },
      { name = 'buffer' },
    }
  })
<

How to disable the documentation window?~

  Simply use the following config:
>
  cmp.setup.filetype({ 'markdown', 'help' }, {
    window = {
      documentation = cmp.config.disable
    }
  })
<

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 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 inside nvim-cmp's key-mapping function:
>
  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 with copilot.vim's preview.
    }
  }
<


How to customize the menu appearance?~

  Have a look at the wiki (https://github.com/hrsh7th/nvim-cmp/wiki).

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