mini.nvim/lua/mini/completion.lua at main · dmun/mini.nvim

Repository navigation

--- *mini.completion* Completion and signature help
--- *MiniCompletion*
--- MIT License Copyright (c) 2021 Evgeni Chasnovski
--- ==============================================================================
--- Key design ideas:
--- - Have an async (with customizable "debounce" delay) "two-stage chain
---   completion": first try to get completion items from LSP client (if set
---   up) and if no result, fallback to custom action.
--- - Managing completion is done as much with Neovim's built-in tools as
---   possible. |popupmenu-completion| is used to show completion suggestions.
--- Features:
--- - Two-stage chain completion:
---     - First stage is an LSP completion implemented via
---       |MiniCompletion.completefunc_lsp()|. It should be set up as either
---       |completefunc| or |omnifunc|. It tries to get completion items from
---       LSP client (via 'textDocument/completion' request). Custom
---       preprocessing of response items is possible (with
---       `MiniCompletion.config.lsp_completion.process_items`), for example
---       with fuzzy matching. By default items directly starting with completed
---       word are kept and are sorted according to LSP specification.
---       Supports `additionalTextEdits`, like auto-import and others (see 'Notes'),
---       and snippet items (best results require |mini.snippets| dependency).
---     - If first stage is not set up or resulted into no candidates, fallback
---       action is executed. The most tested actions are Neovim's built-in
---       insert completion (see |ins-completion|).
--- - Automatic display in floating window of completion item info (via
---   'completionItem/resolve' request) and signature help (with highlighting
---   of active parameter if LSP server provides such information).
---   Signature help is shown if character to cursor's left is a dedicated trigger
---   character (configured in `signatureHelpProvider.triggerCharacters` of LSP
---   server capabilities) and updated without delay if is currently opened.
---   Already shown window for signature help is fixed and is closed when there
---   is nothing to show, its text is different, or when leaving Insert mode.
---   Scroll in either info/signature window with `<C-f>` / `<C-b>` (by default).
--- - Automatic actions are done after some configurable amount of delay. This
---   reduces computational load and allows fast typing (completion and
---   signature help) and item selection (item info)
--- - Force two-stage/fallback completion (`<C-Space>` / `<A-Space>` by default).
--- - LSP kind highlighting ("Function", "Keyword", etc.). Requires Neovim>=0.11.
---   By default uses "lsp" category of |MiniIcons| (if enabled). Can be customized
---   via `config.lsp_completion.process_items` by adding field <kind_hlgroup>
---   (same meaning as in |complete-items|) to items.
--- What it doesn't do:
--- - Many configurable sources.
--- - Automatic mapping of `<CR>`, `<Tab>`, etc. Those tend to have highly
---   variable user expectations. See 'Helpful mappings' for suggestions or
---   use |MiniKeymap.map_multistep()| with `"pmenu_*"` built-in steps.
--- # Dependencies ~
--- Suggested dependencies (provide extra functionality, will work without them):
--- - Enabled |MiniIcons| module to highlight LSP kind (requires Neovim>=0.11).
---   If absent, |MiniCompletion.default_process_items()| does not add highlighting.
---   Also take a look at |MiniIcons.tweak_lsp_kind()|.
--- - Enabled |MiniSnippets| module for better snippet handling (much recommended).
---   If absent and custom snippet insert is not configured, |vim.snippet.expand()|
---   is used on Neovim>=0.10 (nothing extra is done on earlier versions).
---   See |MiniCompletion.default_snippet_insert()|.
--- # Setup ~
--- This module needs a setup with `require('mini.completion').setup({})`
--- (replace `{}` with your `config` table). It will create global Lua table
--- `MiniCompletion` which you can use for scripting or manually (with
--- `:lua MiniCompletion.*`).
--- See |MiniCompletion.config| for `config` structure and default values.
--- You can override runtime config settings locally to buffer inside
--- `vim.b.minicompletion_config` which should have same structure as
--- `MiniCompletion.config`. See |mini.nvim-buffer-local-config| for more details.
--- # Suggested option values ~
--- Some options are set automatically (if not set before |MiniCompletion.setup()|):
--- - 'completeopt' is set to "menuone,noselect" for less intrusive popup.
---   To enable fuzzy matching, manually set to "menuone,noselect,fuzzy". Consider
---   also adding "nosort" flag to preserve initial order when filtering.
--- - 'shortmess' is appended with "c" flag for silent <C-n> fallback.
--- # Snippets ~
--- As per LSP specification, some completion items can be supplied in the form of
--- snippet - a template with both pre-defined text and places (called "tabstops")
--- for user to interactively change/add text during snippet session.
--- In 'mini.completion' items that will insert snippet have "S" symbol shown in
--- the popup (as part of `menu` in |complete-items|). To actually insert a snippet:
--- - Select an item via <C-n> / <C-p>. This will insert item's label (usually not
---   full snippet) first to reduce visual flicker. The full snippet text will be
---   shown in info window if LSP server doesn't provide its own info for an item.
--- - Press <C-y> (|complete_CTRL-Y|) or attempt inserting a non-keyword character
---   (like <CR>; new character will be removed). It will clear text from previous
---   step, set cursor, and call `lsp_completion.snippet_insert` with snippet text.
--- - Press <C-e> (|complete_CTRL-E|) to cancel snippet insert and properly end
---   completion.
--- See |MiniCompletion.default_snippet_insert()| for overview of how to work with
--- inserted snippets.
--- - To stop LSP server from suggesting snippets, disable (set to `false`) the
---   following capability during LSP server start:
---   `textDocument.completion.completionItem.snippetSupport`.
--- - If snippet body doesn't contain tabstops, `lsp_completion.snippet_insert`
---   is not called and text is inserted as is.
--- # Notes ~
--- - A more appropriate (albeit slightly advanced) LSP completion setup is to set
---   it not on every |BufEnter| event (default), but on every attach of LSP client.
---   To do that:
---     - Use in |MiniCompletion.setup()| config: >lua
---       lsp_completion = { source_func = 'omnifunc', auto_setup = false }
---     - Set 'omnifunc' option to exactly `v:lua.MiniCompletion.completefunc_lsp`
---       for every client attach in an |LspAttach| event. Like this: >lua
---       local on_attach = function(args)
---         vim.bo[args.buf].omnifunc = 'v:lua.MiniCompletion.completefunc_lsp'
---       end
---       vim.api.nvim_create_autocmd('LspAttach', { callback = on_attach })
---   This setup is not default to allow simultaneous usage of filetype-specific
---   'omnifunc' (with manual |i_CTRL-X_CTRL-O|) and automated LSP completion.
--- - Use |MiniCompletion.get_lsp_capabilities()| to get/set information about part
---   of LSP specification supported by module. See its help for usability notes.
--- - Uses `vim.lsp.protocol.CompletionItemKind` map in LSP step to show a readable
---   version of item's kind. Modify it directly to change what is displayed.
---   If you have |mini.icons| enabled, take a look at |MiniIcons.tweak_lsp_kind()|.
--- - If you have trouble using custom (overridden) |vim.ui.input|, disable
---   'mini.completion' for input buffer (usually based on its 'filetype').
--- # Comparisons ~
--- - 'hrsh7th/nvim-cmp':
---     - Implements own popup menu to show completion candidates, while this
---       module reuses |ins-completion-menu|.
---     - Has more complex design which allows multiple sources, each in a form of
---       a separate plugin. This module has two built-in: LSP and fallback.
---     - Requires separate plugin for automated signature help.
---     - Implements own "ghost text" feature, while this module does not.
--- - 'Saghen/blink.cmp':
---     - Mostly similar to 'nvim-cmp' comparison: provides more features at the
---       cost of more code and config complexity, while this module is designed
---       to provide only a handful of "enough" features while relying on Neovim's
---       built-in capabilities as much as possible.
---     - Both provide automated signature help out of the box.
--- # Helpful mappings ~
---
--- If there is |mini.keymap| available, prefer using |MiniKeymap.map_multistep()|
--- with `"pmenu_*"` built-in steps. See |MiniKeymap-examples| for examples.
--- To use `<Tab>` and `<S-Tab>` for navigation through completion list, make
--- these mappings: >lua
---   local imap_expr = function(lhs, rhs)
---     vim.keymap.set('i', lhs, rhs, { expr = true })
---   imap_expr('<Tab>',   [[pumvisible() ? "\<C-n>" : "\<Tab>"]])
---   imap_expr('<S-Tab>', [[pumvisible() ? "\<C-p>" : "\<S-Tab>"]])
--- To get more consistent behavior of `<CR>`, you can use this template in
--- your 'init.lua' to make customized mapping: >lua
---   _G.cr_action = function()
---     -- If there is selected item in popup, accept it with <C-y>
---     if vim.fn.complete_info()['selected'] ~= -1 then return '\25' end
---     -- Fall back to plain `<CR>`. You might want to customize according
---     -- to other plugins. For example if 'mini.pairs' is set up, replace
---     -- next line with `return MiniPairs.cr()`
---     return '\r'
---   vim.keymap.set('i', '<CR>', 'v:lua.cr_action()', { expr = true })
--- # Highlight groups ~
--- * `MiniCompletionActiveParameter` - signature active parameter.
--- * `MiniCompletionInfoBorderOutdated` - info window border when text is outdated
---   due to explicit delay during fast movement through candidates.
--- To change any highlight group, modify it directly with |:highlight|.
--- # Disabling ~
--- To disable, set `vim.g.minicompletion_disable` (globally) or
--- `vim.b.minicompletion_disable` (for a buffer) to `true`. Considering high
--- number of different scenarios and customization intentions, writing exact
--- rules for disabling module's functionality is left to user. See
--- |mini.nvim-disabling-recipes| for common recipes.
-- Overall implementation design:
-- - Completion:
--     - On `InsertCharPre` event try to start auto completion. If needed,
--       start timer which after delay will start completion process. Stop this
--       timer if it is not needed.
--     - When timer is activated, first execute LSP source (if set up and there
--       is an active LSP client) by calling built-in complete function
--       (`completefunc` or `omnifunc`) which tries LSP completion by
--       asynchronously sending LSP 'textDocument/completion' request to all
--       LSP clients. When all are done, execute callback which processes
--       results, stores them in LSP cache and reruns built-in complete
--       function which produces completion popup.
--     - If previous step didn't result into any completion, execute (in Insert
--       mode and if no popup) fallback action.
-- - Documentation:
--     - On `CompleteChanged` start auto info with similar to completion timer
--       pattern.
--     - If timer is activated, try these sources of item info:
--         - 'info' field of completion item (see `:h complete-items`).
--         - 'documentation' field of LSP's previously returned result.
--         - 'documentation' field in result of asynchronous
--           'completeItem/resolve' LSP request.
--     - If info doesn't consist only from whitespace, show floating window
--       with its content. Its dimensions and position are computed based on
--       current state of Neovim's data and content itself (which will be
--       displayed wrapped with `linebreak` option).
-- - Signature help (similar to item info):
--     - On `CursorMovedI` start auto signature (if there is any active LSP
--       client) with similar to completion timer pattern. Better event might
--       be `InsertCharPre` but there are issues with 'autopair-type' plugins.
--       Update immediately if already shown or after delay if character to the
--       left is signature help trigger (after delay has passed).
--     - If timer is activated, send 'textDocument/signatureHelp' request to
--       all LSP clients. On callback, process their results. Window is opened
--       if not already with the same text (its characteristics are computed
--       similar to item info). For every LSP client it shows only active
--       signature (in case there are many). If LSP response has data about
--       active parameter, it is highlighted with
--       `MiniCompletionActiveParameter` highlight group.
-- Module definition ==========================================================
local MiniCompletion = {}
local H = {}
--- Module setup
---@param config table|nil Module config table. See |MiniCompletion.config|.
---@usage >lua
---   require('mini.completion').setup() -- use default config
---   -- OR
---   require('mini.completion').setup({}) -- replace {} with your config table
MiniCompletion.setup = function(config)
  -- Export module
  _G.MiniCompletion = MiniCompletion
  -- Setup config
  config = H.setup_config(config)
  -- Apply config
  H.apply_config(config)
  -- Define behavior
  H.create_autocommands(config)
  -- Create default highlighting
  H.create_default_hl()
--- Module config
--- Default values:
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
MiniCompletion.config = {
  -- Delay (debounce type, in ms) between certain Neovim event and action.
  -- This can be used to (virtually) disable certain automatic actions by
  -- setting very high delay time (like 10^7).
  delay = { completion = 100, info = 100, signature = 50 },
  -- Configuration for action windows:
  -- - `height` and `width` are maximum dimensions.
  -- - `border` defines border (as in `nvim_open_win()`; default "single").
  window = {
    info = { height = 25, width = 80, border = nil },
    signature = { height = 25, width = 80, border = nil },
  -- Way of how module does LSP completion
  lsp_completion = {
    -- `source_func` should be one of 'completefunc' or 'omnifunc'.
    source_func = 'completefunc',
    -- `auto_setup` should be boolean indicating if LSP completion is set up
    -- on every `BufEnter` event.
    auto_setup = true,
    -- A function which takes LSP 'textDocument/completion' response items
    -- (each with `client_id` field for item's server) and word to complete.
    -- Output should be a table of the same nature as input. Common use case
    -- is custom filter/sort. Default: `default_process_items`
    process_items = nil,
    -- A function which takes a snippet as string and inserts it at cursor.
    -- Default: `default_snippet_insert` which tries to use 'mini.snippets'
    -- and falls back to `vim.snippet.expand` (on Neovim>=0.10).
    snippet_insert = nil,
  -- Fallback action as function/string. Executed in Insert mode.
  -- To use built-in completion (`:h ins-completion`), set its mapping as
  -- string. Example: set '<C-x><C-l>' for 'whole lines' completion.
  fallback_action = '<C-n>',
  -- Module mappings. Use `''` (empty string) to disable one. Some of them
  -- might conflict with system mappings.
  mappings = {
    -- Force two-step/fallback completions
    force_twostep = '<C-Space>',
    force_fallback = '<A-Space>',
    -- Scroll info/signature window down/up. When overriding, check for
    -- conflicts with built-in keys for popup menu (like `<C-u>`/`<C-o>`
    -- for 'completefunc'/'omnifunc' source function; or `<C-n>`/`<C-p>`).
    scroll_down = '<C-f>',
    scroll_up = '<C-b>',
--minidoc_afterlines_end
-- Module functionality =======================================================
--- Run two-stage completion
---@param fallback boolean|nil Whether to use fallback completion. Default: `true`.
---@param force boolean|nil Whether to force update of completion popup.
---   Default: `true`.
MiniCompletion.complete_twostage = function(fallback, force)
  if H.is_disabled() then return end
  if fallback == nil then fallback = true end
  if force == nil then force = true end
  H.stop_completion()
  H.completion.fallback, H.completion.force = fallback, force
  H.trigger_twostep()
--- Run fallback completion
MiniCompletion.complete_fallback = function()
  if H.is_disabled() then return end
  H.stop_completion()
  H.completion.fallback, H.completion.force = true, true
  H.trigger_fallback()
--- Scroll in info/signature window
--- Designed to be used in |:map-<expr>|.
--- Scrolling is done as if |CTRL-F| and |CTRL-B| is pressed inside target window.
--- Used in default `config.mappings.scroll_xxx` mappings.
---@param direction string One of `"down"` or `"up"`.
---@return boolean Whether scroll is scheduled to be done.
MiniCompletion.scroll = function(direction)
  if not (direction == 'down' or direction == 'up') then H.error('`direction` should be one of "up" or "down"') end
  local win_id = H.is_valid_win(H.info.win_id) and H.info.win_id
    or (H.is_valid_win(H.signature.win_id) and H.signature.win_id or nil)
  if win_id == nil then return false end
  -- Schedule execution as scrolling is not allowed in expression mappings
  local key = direction == 'down' and '\6' or '\2'
  vim.schedule(function()
    if not H.is_valid_win(win_id) then return end
    vim.api.nvim_win_call(win_id, function() vim.cmd('noautocmd normal! ' .. key) end)
  return true
--- Stop actions
--- This stops currently active (because of module delay or LSP answer delay)
--- actions.
--- Designed to be used with |autocmd|. No need to use it directly, everything
--- is setup in |MiniCompletion.setup|.
---@param actions table|nil Array containing any of 'completion', 'info', or
---   'signature' string. Default: array containing all of them.
MiniCompletion.stop = function(actions)
  actions = actions or { 'completion', 'info', 'signature' }
  for _, n in pairs(actions) do
    H.stop_actions[n]()
--- Module's |complete-function|
--- This is the main function which enables two-stage completion. It should be
--- set as one of |completefunc| or |omnifunc|.
--- No need to use it directly, everything is setup in |MiniCompletion.setup|.
MiniCompletion.completefunc_lsp = function(findstart, base)
  -- Early return
  if not H.has_lsp_clients('completionProvider') or H.completion.lsp.status == 'sent' then
    return findstart == 1 and -3 or {}
  -- NOTE: having code for request inside this function enables its use
  -- directly with `<C-x><...>` and as a reaction to `<BS>`.
  if H.completion.lsp.status ~= 'received' then
    -- NOTE: it is CRUCIAL to make LSP request on the first call to
    -- 'complete-function' (as in Vim's help). This is due to the fact that
    -- cursor line and position are different on the first and second calls to
    -- 'complete-function'. For example, when calling this function at the end
    -- of the line '  he', cursor position on the first call will be
    -- (<linenum>, 4) and line will be '  he' but on the second call -
    -- (<linenum>, 2) and '  ' (because 2 is a column of completion start).
    -- This request is not executed on second call because it returns `-3` on
    -- first call (which means cancel and leave completion mode).
    H.make_completion_request()
    -- End completion and wait for LSP callback to re-trigger this
    return findstart == 1 and -3 or {}
    if findstart == 1 then
      H.completion.start_pos = H.get_completion_start(H.completion.lsp.result)
      return H.completion.start_pos[2]
    local is_incomplete = false
    local all_items = H.process_lsp_response(H.completion.lsp.result, function(response, client_id)
      is_incomplete = is_incomplete or (response.isIncomplete == true)
      -- Response can be `CompletionList` with 'items' field plus their
      -- defaults or `CompletionItem[]`
      local items = H.table_get(response, { 'items' }) or response
      if type(items) ~= 'table' then return {} end
      items = H.apply_item_defaults(items, response.itemDefaults)
      for _, item in ipairs(items) do
        item.client_id = client_id
      return items
    -- Process items
    local process_items = H.get_config().lsp_completion.process_items or MiniCompletion.default_process_items
    all_items = process_items(all_items, base)
    local candidates = H.lsp_completion_response_items_to_complete_items(all_items)
    H.completion.lsp.status = 'done'
    H.completion.lsp.is_incomplete = is_incomplete
    -- Maybe trigger fallback action
    if vim.tbl_isempty(candidates) and H.completion.fallback then return H.trigger_fallback() end
    -- Track from which source is current popup
    H.completion.source = 'lsp'
    return candidates
--- Default processing of LSP items
--- - Filter and sort items according to supplied method.
--- - Arrange items further by completion item kind according to their priority.
--- - If |MiniIcons| is enabled, add <kind_hlgroup> based on the "lsp" category.
--- Example of forcing fuzzy matching, filtering out `Text` items, and putting
--- `Snippet` items last: >lua
---   local kind_priority = { Text = -1, Snippet = 99 }
---   local opts = { filtersort = 'fuzzy', kind_priority = kind_priority }
---   local process_items = function(items, base)
---     return MiniCompletion.default_process_items(items, base, opts)
---   require('mini.completion').setup({
---     lsp_completion = { process_items = process_items },
---@param items table Array of items from LSP response.
---@param base string Base for which completion is done. See |complete-functions|.
---@param opts table|nil Options. Possible fields:
---   - <filtersort> `(string|function)` - method of filtering and sorting items.
---     If string, should be one of the following:
---       - `'prefix'` - filter out items not starting with `base`, sort according
---         to LSP specification. Use `filterText` and `sortText` respectively with
---         fallback to `label`.
---       - `'fuzzy'` - filter and sort with |matchfuzzy()| using `filterText`.
---       - `'none'` - no filter and no sort.
---     If callable, should take `items` and `base` arguments and return items array.
---     Default: `'fuzzy'` if 'completeopt' contains "fuzzy", `'prefix'` otherwise.
---   - <kind_priority> `(table)` - map of completion item kinds (like `Variable`,
---     `Snippet`; see string keys of `vim.lsp.protocol.CompletionItemKind`) to
---     their numerical priority. It will be used after applying <filtersort> to
---     arrange by completion item kind: items with negative priority kinds will
---     be filtered out, the rest are sorted by decreasing priority (preserving
---     order in case of same priority).
---     Priorities can be any number, only matters how they compare to each other.
---     Value 100 is used for missing kinds (i.e. not all can be supplied).
---     Default: `{}` (all equal priority).
---@return table Array of processed items from LSP response.
MiniCompletion.default_process_items = function(items, base, opts)
  opts = opts or {}
  -- Filter+sort (important with frequent `isIncomplete`)
  local fs = opts.filtersort or (vim.o.completeopt:find('fuzzy') ~= nil and 'fuzzy' or 'prefix')
  if type(fs) == 'string' then fs = H.filtersort_methods[fs] end
  if not vim.is_callable(fs) then H.error('`filtersort` should be callable or one of "prefix", "fuzzy", "none"') end
  local res = fs(items, base)
  -- Arrange by kind
  if opts.kind_priority ~= nil then res = H.lsp_arrange_by_kind(res, opts.kind_priority) end
  -- Possibly add "kind" highlighting
  if _G.MiniIcons == nil then return res end
  local add_kind_hlgroup = H.make_add_kind_hlgroup()
  for _, item in ipairs(res) do
    add_kind_hlgroup(item)
  return res
--- Default snippet insert
--- Order of preference:
--- - Use |MiniSnippets| if set up (i.e. there is `require('mini.snippets').setup()`).
--- - Use |vim.snippet.expand()| on Neovim>=0.10
--- - Add snippet text at cursor as is.
--- After snippet is inserted, user is expected to navigate/jump between dedicated
--- places (tabstops) to adjust inserted text as needed:
--- - |MiniSnippets| by default uses <C-l> / <C-h> to jump to next/previous tabstop.
---   Can be adjusted in `mappings` of |MiniSnippets.config|.
--- - |vim.snippet| on Neovim=0.10 requires manually created mappings for jumping
---   between tabstops (see |vim.snippet.jump()|). Neovim>=0.11 sets them up
---   automatically to <Tab> / <S-Tab> (if not overridden by user).
--- End session by navigating all the way to the last tabstop. In 'mini.snippets':
--- - Also make any text edit or exit Insert mode to end the session. This allows
---   smoother navigation to previous tabstops in case of a lately spotted typo.
--- - Press `<C-c>` to force session stop.
---@param snippet string Snippet body to insert at cursor.
---@seealso |MiniSnippets-session| if 'mini.snippets' is set up.
--- |vim.snippet| for Neovim's built-in snippet engine.
MiniCompletion.default_snippet_insert = function(snippet)
  if _G.MiniSnippets then
    local insert = MiniSnippets.config.expand.insert or MiniSnippets.default_insert
    return insert({ body = snippet })
  if vim.fn.has('nvim-0.10') == 1 then return vim.snippet.expand(snippet) end
  local pos, lines = vim.api.nvim_win_get_cursor(0), vim.split(snippet, '\n')
  vim.api.nvim_buf_set_text(0, pos[1] - 1, pos[2], pos[1] - 1, pos[2], lines)
  local n = #lines
  local new_pos = n == 1 and { pos[1], pos[2] + lines[n]:len() } or { pos[1] + n - 1, lines[n]:len() }
  vim.api.nvim_win_set_cursor(0, new_pos)
--- Get client LSP capabilities
--- Possible usages:
--- - On Neovim>=0.11 via |vim.lsp.config()|: >lua
---   vim.lsp.config('*', {capabilities = MiniCompletion.get_lsp_capabilities()})
--- - Together with |vim.lsp.protocol.make_client_capabilities()| to get the full
---   client capabilities (use |vim.tbl_deep_extend()| to merge tables).
--- - Manually execute `:=MiniCompletion.get_lsp_capabilities()` to see the info.
--- - It declares completion resolve support for `'additionalTextEdits'` (usually
---   used for something like auto-import feature), as it is usually a more robust
---   choice for various LSP servers. As a consequence, this requires selecting
---   completion item and waiting for `config.delay.info` milliseconds plus server
---   response time (i.e. until information window shows relevant text).
---   To not have to wait after an item selection and if the server handles absent
---   `'additionalTextEdits'` well, set `opts.resolve_additional_text_edits = false`.
---@param opts table|nil Options. Possible fields:
---   - <resolve_additional_text_edits> `(boolean)` - whether to declare
---     `'additionalTextEdits'` as possible to resolve in `'completionitem/resolve'`
---     requrest. See above "Notes" section.
---     Default: `true`.
---@return table Data about LSP capabilities supported by 'mini.completion'. Has same
---   structure as relevant parts of |vim.lsp.protocol.make_client_capabilities()|.
---@seealso Structures of `completionClientCapabilities` and `signatureHelpClientCapabilities`
--- at https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification
MiniCompletion.get_lsp_capabilities = function(opts)
  opts = vim.tbl_extend('force', { resolve_additional_text_edits = true }, opts or {})
  local resolve_support = { 'detail', 'documentation' }
  if opts.resolve_additional_text_edits then table.insert(resolve_support, 1, 'additionalTextEdits') end
    textDocument = {
      -- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#completionClientCapabilities
      completion = {
        dynamicRegistration = false,
        completionItem = {
          snippetSupport = true,
          commitCharactersSupport = false,
          documentationFormat = { 'markdown', 'plaintext' },
          deprecatedSupport = false,
          preselectSupport = false,
          tagSupport = { valueSet = {} },
          insertReplaceSupport = true,
          resolveSupport = { properties = resolve_support },
          insertTextModeSupport = { valueSet = { 1 } },
          labelDetailsSupport = true,
        completionItemKind = {
          valueSet = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25 },
        contextSupport = true,
        insertTextMode = 1,
        completionList = {
          itemDefaults = { 'commitCharacters', 'editRange', 'insertTextFormat', 'insertTextMode', 'data' },
      -- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#signatureHelpClientCapabilities
      signatureHelp = {
        dynamicRegistration = false,
        signatureInformation = {
          documentationFormat = { 'markdown', 'plaintext' },
          parameterInformation = {
            labelOffsetSupport = true,
          activeParameterSupport = true,
        contextSupport = false,
-- Helper data ================================================================
-- Module default config
H.default_config = vim.deepcopy(MiniCompletion.config)
-- Track Insert mode changes
H.text_changed_id = 0
-- Namespace for highlighting
H.ns_id = vim.api.nvim_create_namespace('MiniCompletion')
-- Commonly used key sequences
  completefunc = vim.api.nvim_replace_termcodes('<C-x><C-u>', true, false, true),
  omnifunc = vim.api.nvim_replace_termcodes('<C-x><C-o>', true, false, true),
  ctrl_n = vim.api.nvim_replace_termcodes('<C-g><C-g><C-n>', true, false, true),
-- Caches for different actions -----------------------------------------------
-- Field `lsp` is a table describing state of all used LSP requests. It has the
-- following structure:
-- - id: identifier (consecutive numbers).
-- - status: one of 'sent', 'received', 'done', 'canceled'
-- - is_incomplete: whether request was incomplete and require recomputing
-- - result: result of request.
-- - cancel_fun: function which cancels current request.
-- Cache for completion
H.completion = {
  fallback = true,
  force = false,
  source = nil,
  text_changed_id = 0,
  timer = vim.loop.new_timer(),
  lsp = { id = 0, status = nil, is_incomplete = false, result = nil, resolved = {}, cancel_fun = nil, context = nil },
  start_pos = {},
-- Cache for completion item info
  bufnr = nil,
  event = nil,
  timer = vim.loop.new_timer(),
  win_id = nil,
  lsp = { id = 0, status = nil, result = nil, cancel_fun = nil },
-- Cache for signature help
H.signature = {
  bufnr = nil,
  text = nil,
  timer = vim.loop.new_timer(),
  win_id = nil,
  lsp = { id = 0, status = nil, result = nil, cancel_fun = nil },
-- Helper functionality =======================================================
-- Settings -------------------------------------------------------------------
H.setup_config = function(config)
  H.check_type('config', config, 'table', true)
  config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
  H.check_type('delay', config.delay, 'table')
  H.check_type('window', config.window, 'table')
  H.check_type('lsp_completion', config.lsp_completion, 'table')
  if not (type(config.fallback_action) == 'function' or type(config.fallback_action) == 'string') then
    H.error('`fallback_action` should be function or string, not ' .. type(config.fallback_action))
  H.check_type('mappings', config.mappings, 'table')
  H.check_type('delay.completion', config.delay.completion, 'number')
  H.check_type('delay.info', config.delay.info, 'number')
  H.check_type('delay.signature', config.delay.signature, 'number')
  H.check_type('window.info', config.window.info, 'table')
  H.check_type('window.signature', config.window.signature, 'table')
  if not (config.lsp_completion.source_func == 'completefunc' or config.lsp_completion.source_func == 'omnifunc') then
    H.error('`lsp_completion.source_func` should be one of "completefunc" or "omnifunc"')
  H.check_type('lsp_completion.auto_setup', config.lsp_completion.auto_setup, 'boolean')
  H.check_type('lsp_completion.process_items', config.lsp_completion.process_items, 'callable', true)
  H.check_type('lsp_completion.snippet_insert', config.lsp_completion.snippet_insert, 'callable', true)
  H.check_type('mappings.force_twostep', config.mappings.force_twostep, 'string')
  H.check_type('mappings.force_fallback', config.mappings.force_fallback, 'string')
  H.check_type('mappings.scroll_down', config.mappings.scroll_down, 'string')
  H.check_type('mappings.scroll_up', config.mappings.scroll_up, 'string')
  local is_string_or_array = function(x) return type(x) == 'string' or H.islist(x) end
  H.check_type('window.info.height', config.window.info.height, 'number')
  H.check_type('window.info.width', config.window.info.width, 'number')
  if not is_string_or_array(config.window.info.border or 'single') then
    H.error('`config.window.info.border` should be either string or array, not ' .. type(config.window.info.border))
  H.check_type('window.signature.height', config.window.signature.height, 'number')
  H.check_type('window.signature.width', config.window.signature.width, 'number')
  if not is_string_or_array(config.window.signature.border or 'single') then
    H.error(
      '`config.window.signature.border` should be either string or array, not ' .. type(config.window.signature.border)
  return config
H.apply_config = function(config)
  MiniCompletion.config = config
  H.map('i', config.mappings.force_twostep, MiniCompletion.complete_twostage, { desc = 'Complete with two-stage' })
  H.map('i', config.mappings.force_fallback, MiniCompletion.complete_fallback, { desc = 'Complete with fallback' })
  local map_scroll = function(lhs, direction)
    local rhs = function() return MiniCompletion.scroll(direction) and '' or lhs end
    H.map('i', lhs, rhs, { expr = true, desc = 'Scroll info/signature ' .. direction })
  map_scroll(config.mappings.scroll_down, 'down')
  map_scroll(config.mappings.scroll_up, 'up')
  -- Try setting suggested option values
  -- - More common completion behavior
  local was_set = vim.api.nvim_get_option_info2('completeopt', { scope = 'global' }).was_set
  if not was_set then vim.o.completeopt = 'menuone,noselect' end
  -- - Don't show ins-completion-menu messages ("C" is default on Neovim>=0.10)
  local shortmess_flags = 'c' .. (vim.fn.has('nvim-0.10') == 0 and 'C' or '')
  was_set = vim.api.nvim_get_option_info2('shortmess', { scope = 'global' }).was_set
  if not was_set then vim.opt.shortmess:append(shortmess_flags) end
H.create_autocommands = function(config)
  local gr = vim.api.nvim_create_augroup('MiniCompletion', {})
  local au = function(event, pattern, callback, desc)
    vim.api.nvim_create_autocmd(event, { group = gr, pattern = pattern, callback = callback, desc = desc })
  au('InsertCharPre', '*', H.auto_completion, 'Auto show completion')
  au('CompleteChanged', '*', H.auto_info, 'Auto show info')
  au('CursorMovedI', '*', H.auto_signature, 'Auto show signature')
  au('ModeChanged', 'i*:[^i]*', function() MiniCompletion.stop() end, 'Stop completion')
  au('CompleteDonePre', '*', H.on_completedonepre, 'On CompleteDonePre')
  au('TextChangedI', '*', H.on_text_changed_i, 'On TextChangedI')
  au('TextChangedP', '*', H.on_text_changed_p, 'On TextChangedP')
  if config.lsp_completion.auto_setup then
    local source_func = config.lsp_completion.source_func
    local callback = function() vim.bo[source_func] = 'v:lua.MiniCompletion.completefunc_lsp' end
    au('BufEnter', '*', callback, 'Set completion function')
  au('ColorScheme', '*', H.create_default_hl, 'Ensure colors')
  au('FileType', 'TelescopePrompt', function() vim.b.minicompletion_disable = true end, 'Disable locally')
H.create_default_hl = function()
  vim.api.nvim_set_hl(0, 'MiniCompletionActiveParameter', { default = true, link = 'LspSignatureActiveParameter' })
  vim.api.nvim_set_hl(0, 'MiniCompletionInfoBorderOutdated', { default = true, link = 'DiagnosticFloatingWarn' })
H.is_disabled = function() return vim.g.minicompletion_disable == true or vim.b.minicompletion_disable == true end
H.get_config = function(config)
  return vim.tbl_deep_extend('force', MiniCompletion.config, vim.b.minicompletion_config or {}, config or {})
-- Autocommands ---------------------------------------------------------------
H.auto_completion = function()
  if H.is_disabled() then return end
  H.completion.timer:stop()
  local is_incomplete = H.completion.lsp.is_incomplete
  local is_trigger = H.is_lsp_trigger(vim.v.char, 'completion')
  local force = is_trigger or is_incomplete
  if force then
    -- Force fresh LSP completion if needed. Check before checking pumvisible
    -- because it should be forced even if there are visible candidates.
    -- Keep positive `is_incomplete` to allow fast typing and not "forget" that
    -- list was incomplete after the second fast key press. This will force LSP
    -- completion until `isIncomplete=false` response or general `stop()`.
    H.stop_completion(false, is_incomplete)
  elseif H.pumvisible() then
    -- Do nothing if popup is visible. `H.pumvisible()` might be `true` even if
    -- there is no popup. It is common when manually typing candidate followed
    -- by an LSP trigger (like ".").
    -- Keep completion source as it is needed all time when popup is visible.
    -- Keep resolved candidates because they should be relevant in this route.
    return H.stop_completion(true, false, true)
  elseif not H.is_char_keyword(vim.v.char) then
    -- Stop everything if inserted character is not appropriate. Check this
    -- after popup check to allow completion candidates to have bad characters.
    return H.stop_completion(false)
  -- Start non-forced completion with fallback or forced LSP source for trigger
  H.completion.fallback, H.completion.force = not force, force
  -- Cache id of Insert mode "text changed" event for a later tracking (reduces
  -- false positive delayed triggers). The intention is to trigger completion
  -- after the delay only if text wasn't changed during waiting. Using only
  -- `InsertCharPre` is not enough though, as not every Insert mode change
  -- triggers `InsertCharPre` event (notable example - hitting `<CR>`).
  -- Also, using `+ 1` here because it is a `Pre` event and needs to cache
  -- after inserting character.
  H.completion.text_changed_id = H.text_changed_id + 1
  -- If completion was requested after 'lsp' source exhausted itself (there
  -- were matches on typing start, but they disappeared during filtering), call
  -- fallback immediately.
  if H.completion.source == 'lsp' then return H.trigger_fallback() end
  -- Set completion context with information about how it was triggered
  -- Prefer manual `TriggerCharacter` over automated `...ForIncomplete...`.
  local trigger_kind_name = is_trigger and 'TriggerCharacter'
    or (is_incomplete and 'TriggerForIncompleteCompletions' or 'Invoked')
  local trigger_kind = vim.lsp.protocol.CompletionTriggerKind[trigger_kind_name]
  local trigger_char = trigger_kind_name == 'TriggerCharacter' and vim.v.char or nil
  H.completion.lsp.context = { triggerKind = trigger_kind, triggerCharacter = trigger_char }
  -- Debounce delay improves experience (can type fast without many popups)
  -- Request right away if improving incomplete suggestions (less flickering),
  -- but still with `vim.schedule` because line is still not up to date during
  -- `InsertCharPre` event.
  local delay = is_incomplete and 0 or H.get_config().delay.completion
  H.completion.timer:start(delay, 0, vim.schedule_wrap(H.trigger_twostep))
H.auto_info = function()
  if H.is_disabled() then return end
  -- Stop current LSP request that tries to get already not current data
  H.cancel_lsp({ H.info })
  -- Update metadata before leaving to register a `CompleteChanged` event
  H.info.timer:stop()
  H.info.event = vim.v.event
  H.info.id = H.info.id + 1
  -- Stop showing window if no candidate is selected
  local completed_item = H.info.event.completed_item
  if completed_item.word == nil then
    return vim.schedule(function() H.close_action_window(H.info, true) end)
  -- Show info content without delay for visited and resolved LSP item.
  -- Otherwise delay to not spam LSP requests on up/down navigation.
  local item_id = H.table_get(completed_item, { 'user_data', 'lsp', 'item_id' })
  local is_resolved = item_id == nil or H.completion.lsp.resolved[item_id] ~= nil
  local delay = is_resolved and 0 or H.get_config().delay.info
  -- Mark visually that currently shown content will be outdated for a while
  local win_id = H.info.win_id
  if H.is_valid_win(win_id) and delay > 0 then
    vim.wo[win_id].winhighlight = vim.wo[win_id].winhighlight .. ',FloatBorder:MiniCompletionInfoBorderOutdated'
  H.info.timer:start(delay, 0, vim.schedule_wrap(H.show_info_window))
H.auto_signature = function()
  if H.is_disabled() then return end
  H.signature.timer:stop()
  if not H.has_lsp_clients('signatureHelpProvider') then return end
  local is_shown = H.is_valid_win(H.signature.win_id)
  local left_char_is_trigger = H.is_lsp_trigger(H.get_left_char(), 'signature')
  if not (is_shown or left_char_is_trigger) then return end
  local delay = is_shown and 0 or H.get_config().delay.signature
  H.signature.timer:start(delay, 0, vim.schedule_wrap(H.show_signature_window))
H.on_completedonepre = function()
  -- Do nothing if it is triggered inside `trigger_lsp()` as a result of
  -- emulating 'completefunc'/'omnifunc' keys. This can happen if popup is
  -- visible and pressing keys first hides it with 'CompleteDonePre' event.
  if H.completion.lsp.status == 'received' then return end
  -- Do extra actions for LSP completion items
  local lsp_data = H.table_get(vim.v.completed_item, { 'user_data', 'lsp' })
  if lsp_data ~= nil then H.make_lsp_extra_actions(lsp_data) end
  -- Stop processes
  MiniCompletion.stop({ 'completion', 'info' })
H.on_text_changed_i = function()
  -- Track Insert mode changes
  H.text_changed_id = H.text_changed_id + 1
  -- Stop 'info' processes in case no completion event is triggered but popup
  -- is not visible. See https://github.com/neovim/neovim/issues/15077
  H.stop_info()
H.on_text_changed_p = function()
  -- Track Insert mode changes
  H.text_changed_id = H.text_changed_id + 1
-- Completion triggers --------------------------------------------------------
H.trigger_twostep = function()
  -- Trigger only in Insert mode and if text didn't change after trigger
  -- request, unless completion is forced
  -- NOTE: check for `text_changed_id` equality is still not 100% solution as
  -- there are cases when, for example, `<CR>` is hit just before this check.
  -- Because of asynchronous id update and this function call (called after
  -- delay), these still match.
  local allow_trigger = (vim.fn.mode() == 'i')
    and (H.completion.force or (H.completion.text_changed_id == H.text_changed_id))
  if not allow_trigger then return end
  if H.has_lsp_clients('completionProvider') and H.has_lsp_completion() then
    H.trigger_lsp()
  elseif H.completion.fallback then
    H.trigger_fallback()
H.trigger_lsp = function()
  -- Check for popup visibility is needed to reduce flickering.
  -- Possible issue timeline (with 100ms delay with set up LSP):
  -- 0ms: Key is pressed.
  -- 100ms: LSP is triggered from first key press.
  -- 110ms: Another key is pressed.
  -- 200ms: LSP callback is processed, triggers complete-function which
  --   processes "received" LSP request.
  -- 201ms: LSP request is processed, completion is (should be almost
  --   immediately) provided, request is marked as "done".
  -- 210ms: LSP is triggered from second key press. As previous request is
  --   "done", it will once make whole LSP request. Having check for visible
  --   popup should prevent here the call to complete-function.
  -- Do not trigger if not needed and/or allowed
  if vim.fn.mode() ~= 'i' or (H.pumvisible() and not H.completion.force) then return end
  -- Overall idea: first make LSP request and re-trigger this same function
  -- inside its callback to take the "received" route. This reduces flickering
  -- in case popup is visible (like for `isIncomplete` and trigger characters)
  -- as pressing 'completefunc'/'omnifunc' keys first hides completion menu.
  -- There are still minor visual defects: typing new character reduces number
  -- of matched items which can visually shrink popup while later increase it
  -- again after LSP response is received. This is usually fine (especially
  -- with not huge 'pumheight').
  if H.completion.lsp.status ~= 'received' then return H.make_completion_request() end

View remainder of file in raw view

FilesExpand file tree

completion.lua

Latest commit

History

completion.lua

File metadata and controls