Comandos de usuario: argumentos, rangos, bang y completado

Un mapeo es un atajo: rápido, silencioso, sin parámetros. Un comando de usuario es lo contrario: descubrible, argumentable, componible con rangos y con la historia de la línea de comandos. No compiten, se complementan. Casi toda funcionalidad seria de tu configuración debería existir primero como comando y solo después, si la usas a diario, recibir un atajo que lo invoque.

Anatomía de la declaración

La función toma un nombre, un cuerpo y una tabla de opciones. El nombre debe empezar por mayúscula y contener solo letras, dígitos y guiones bajos: esa restricción existe para que los comandos de usuario nunca colisionen con los comandos internos, que empiezan por minúscula.

vim.api.nvim_create_user_command('Ordenar', function(opts)
  local ini, fin = opts.line1, opts.line2
  local lineas = vim.api.nvim_buf_get_lines(0, ini - 1, fin, false)
  table.sort(lineas, function(a, b)
    if opts.bang then return a > b end
    return a < b
  end)
  vim.api.nvim_buf_set_lines(0, ini - 1, fin, false, lineas)
end, {
  range = '%',
  bang = true,
  desc = 'Ordena el rango indicado; con bang, en orden inverso',
})

Ese comando ya se comporta como uno nativo: :Ordenar sobre todo el archivo, :10,20Ordenar sobre un rango explícito, :'<,'>Ordenar sobre la selección visual y :Ordenar! invirtiendo el criterio. Nada de eso lo has programado; lo has declarado.

La tabla de contexto del callback

El callback recibe un único argumento: una tabla con todo lo que el usuario tecleó, ya desmenuzado. Conocerla de memoria ahorra un viaje constante a la ayuda.

Ese último punto es el que separa un comando aficionado de uno indistinguible de los nativos. Si reenvías smods, el usuario puede escribir :vertical Ayuda lua o :tab Ayuda lua y tu comando obedecerá sin que tú programes nada al respecto.

vim.api.nvim_create_user_command('Ayuda', function(opts)
  vim.api.nvim_cmd({ cmd = 'help', args = opts.fargs, mods = opts.smods }, {})
end, {
  nargs = '?',
  complete = 'help',
  desc = 'Ayuda que respeta vertical, tab y silent',
})

Rangos y conteos: dos cosas distintas

Un rango describe una región: dos números que delimitan líneas, buffers o pestañas según addr. Un conteo describe una cantidad: un solo número que el usuario antepone. :3Cerrar significa cosas muy distintas si declaraste range (líneas 1 a 3, o la línea 3) o count (tres veces, o el elemento tres). Elige según la naturaleza semántica del verbo: si actúa sobre texto, quieres rango; si actúa sobre entidades enumerables o repeticiones, quieres conteo.

vim.api.nvim_create_user_command('Recientes', function(opts)
  local n = opts.count
  for _, buf in ipairs(vim.api.nvim_list_bufs()) do
    if n <= 0 then break end
    if vim.api.nvim_buf_is_loaded(buf) then
      print(vim.api.nvim_buf_get_name(buf))
      n = n - 1
    end
  end
end, { count = 5, desc = 'Lista los N buffers cargados más recientes' })

flowchart LR
U[El usuario teclea el comando] --> P[Neovim analiza rango bang y argumentos]
P --> T[Construye la tabla de contexto]
T --> C[Invoca tu callback de Lua]
C --> E[Efecto sobre el buffer o la interfaz]
P --> K[Si pulsa Tab llama a tu funcion de completado]
K --> L[Devuelves la lista ya filtrada]
style T fill:#cba6f7,color:#11111b
style C fill:#89b4fa,color:#11111b
style L fill:#a6e3a1,color:#11111b

Completado personalizado

La opción complete acepta una de las cadenas predefinidas de Vim, como file, buffer, dir, help o highlight, o bien una función de Lua. Esa función recibe tres argumentos: la palabra parcial que se está completando, la línea de comandos entera y la posición del cursor. Y aquí está el detalle que sorprende a todo el mundo la primera vez: Neovim no filtra por ti. Tu función se comporta como customlist, así que devuelve exactamente lo que quieres ofrecer, ya recortado.

local temas = { 'catppuccin', 'gruvbox', 'kanagawa', 'rose-pine', 'tokyonight' }

vim.api.nvim_create_user_command('Tema', function(opts)
  vim.cmd.colorscheme(opts.args)
end, {
  nargs = 1,
  desc = 'Cambia el tema activo',
  complete = function(lead)
    return vim.tbl_filter(function(t) return vim.startswith(t, lead) end, temas)
  end,
})

El segundo y el tercer argumento permiten un completado contextual: mirando la línea ya escrita puedes ofrecer subcomandos en la primera posición y sus opciones en la segunda, que es la técnica con la que plugins como el gestor de paquetes construyen interfaces de un solo comando. Para acotar el alcance existen nvim_buf_create_user_command, que instala el comando solo en un buffer, y nvim_del_user_command para retirarlo.