How to correctly write a cmdline source for custom user command with docs

[ibhagwan]

Hi @hrsh7th and ty for your wonderful work.

For context, WIP code for my custom nvim-cmp source can be found at https://github.com/ibhagwan/fzf-lua/blob/cmp_src/lua/fzf-lua/cmp_src.lua.

What I'm currently trying to achieve is the following:

• Command and options completion for FzfLua ... via nvim_create_user_command.complete
• If nvim-cmp isn't installed the command displays regular neovim completion
• However, if I detect that nvim-cmp/cmdline is available, I inject a completion source and add it to cmdline (so the user doesn't have to configure anything):

From the above linked code

function Src._register_cmdline()
  local ok, cmp = pcall(require, "cmp")
  if not ok then return end
  cmp.register_source("FzfLua", Src)
  local cmdline_cfg = require("cmp.config").cmdline
  local has_fzf_lua = false
  for _, s in ipairs(cmdline_cfg[":"].sources or {}) do
    if s.name == "FzfLua" then
      has_fzf_lua = true
    end
  end
  if not has_fzf_lua then
    if cmdline_cfg[":"] then
      table.insert(cmdline_cfg[":"].sources or {}, {
        group_index = 1,
        name = "FzfLua",
        option = {}
      })
    end
  end
end

Once registered, I am able to display docs via the Source:resolve callback (thus providing documentaiton for commands/options).

I have a couple of quesions:

1. Is the above the correct way of injecting a registered source to the commad line completion module?

2. My custom source is only called after I start typing a single letter due to my config setting completion.keyword_lengh=1 but that causes an issue where my docs aren't displayed on the initial completion, for example, after typing :FzfLua <space> the nvim-cmp source appears as [Cmdline] and the docs aren't being resolved:
   
   After typing :FzfLua f, my source is being called (note the source name [FzfLua]) and I see the docs:
   

Is there a better way to write a completion source that can generate docs for a user command regardless of the keyword_length setting?

[ibhagwan]

After some more research I found #1197 (comment) which implies nvim-cmp does not support keyword_length=0? Is that still accurate?

I attempted another approach, instead of injecting the source into cmp.config.cmdline I called cmp.complete manually in the user command complete callback, however that causes another issue where the completion will not be called a 2nd time until space is pressed again.

For example input :FzfLua f<complete><space>: with the below user command:

vim.api.nvim_create_user_command("FzfLua", function(opts)
    require("fzf-lua.cmd").run_command(unpack(opts.fargs))
end, {
  nargs = "*",
  range = true,
  complete = function(_, line)
    print("called", #line, line, line:match("%s+$") ~= nil)
})

The :messages output will contain (callback is called after writing files<space>):

However, after calling cmp.complete, I have to press space twice to trigger completion after files as f<complete><space> does not get called at all:

vim.api.nvim_create_user_command("FzfLua", function(opts)
    require("fzf-lua.cmd").run_command(unpack(opts.fargs))
end, {
  nargs = "*",
  range = true,
  complete = function(_, line)
    -- without calling `cmp.complete` this gets called right after
    print("called", #line, line, line:match("%s+$") ~= nil)
    vim.schedule(function()
      require("cmp").complete({
        config = {
          sources = {
            { name = "FzfLua" }
          }
        }
      })
    end)
  end,
})

@hrsh7th, is this by design or is this a bug?