Operadores propios: operatorfunc y la gramática extendida

Vim tiene una docena escasa de operadores: d, c, y, gu, gU, >, <, =, !. Todos comparten una propiedad que parecía privilegio del núcleo: aceptan cualquier movimiento y cualquier objeto de texto sin conocerlos de antemano. operatorfunc rompe ese privilegio y te deja añadir verbos al idioma, con dominio completo sobre la gramática y con repetición mediante el punto incluida.

El protocolo de g@

g@ es una tecla que se comporta como un operador: al pulsarla, Neovim entra en modo operator-pending y espera un movimiento o un objeto de texto. Cuando lo recibe, calcula la región afectada, coloca las marcas '[ y '] en sus extremos, e invoca la función indicada en la opción operatorfunc pasándole un único argumento: la cadena char, line o block según cómo se determinó la región.

Es decir, tú no analizas movimientos ni objetos de texto. Neovim resuelve toda la gramática y te entrega el resultado ya masticado: dos marcas y un tipo. Tu función solo tiene que actuar sobre esa región.

sequenceDiagram
participant U as Usuario
participant N as Neovim
participant F as Tu funcion
U->>N: pulsa g arroba
N->>N: entra en operator pending
U->>N: teclea un movimiento o un objeto
N->>N: calcula la region y fija las marcas de corchete
N->>F: invoca operatorfunc con char line o block
F->>N: lee las marcas y modifica el buffer
N->>U: guarda la accion para el punto

Escribir el operador

El patrón idiomático mete dos responsabilidades en la misma función y distingue entre ellas por el argumento. Si llega nil, es que la estás invocando desde el mapeo: fijas operatorfunc y devuelves g@. Si llega una cadena, es Neovim quien te llama tras resolver el movimiento, y toca trabajar.

-- lua/dios/ops.lua
local M = {}

local function ordenar_rango(ini, fin)
  local lineas = vim.api.nvim_buf_get_lines(0, ini - 1, fin, false)
  table.sort(lineas)
  vim.api.nvim_buf_set_lines(0, ini - 1, fin, false, lineas)
end

function M.ordenar(kind)
  if kind == nil then
    vim.o.operatorfunc = "v:lua.require'dios.ops'.ordenar"
    return 'g@'
  end
  ordenar_rango(
    vim.api.nvim_buf_get_mark(0, '[')[1],
    vim.api.nvim_buf_get_mark(0, ']')[1]
  )
end

function M.ordenar_visual()
  ordenar_rango(
    vim.api.nvim_buf_get_mark(0, '<')[1],
    vim.api.nvim_buf_get_mark(0, '>')[1]
  )
end

return M

La cadena v:lua.require'dios.ops'.ordenar es una forma especial que Neovim reconoce: permite apuntar operatorfunc a un módulo sin ensuciar el espacio global. Como operatorfunc es una opción global, esta indirección evita que dos operadores tuyos se pisen entre sí.

local ops = require('dios.ops')

vim.keymap.set('n', 'gs', ops.ordenar, { expr = true, desc = 'Ordenar las líneas del movimiento' })
vim.keymap.set('n', 'gss', function() return ops.ordenar() .. '_' end,
  { expr = true, desc = 'Ordenar la línea actual' })
vim.keymap.set('x', 'gs', ':<C-u>lua require("dios.ops").ordenar_visual()<CR>',
  { silent = true, desc = 'Ordenar la selección' })

Tres detalles con mucha densidad. El primero: gss devuelve g@_, y _ es el movimiento lineal que abarca la línea actual, replicando la convención nativa de que duplicar el operador lo aplica a la línea. El segundo: la variante visual usa dos puntos con <C-u> porque al abandonar el modo visual se fijan las marcas '< y '>, y <C-u> limpia el rango que Neovim inserta solo. El tercero: el mapeo normal es expr porque la función devuelve teclas, no ejecuta el efecto.

Leer la región según el tipo

Para un operador lineal basta con el número de línea de las marcas, como en el ejemplo anterior. Para uno que actúa carácter a carácter necesitas también las columnas, y ahí entra getregion, que resuelve de una vez el trabajo sucio de recortar la primera y la última línea.

function M.contar(kind)
  if kind == nil then
    vim.o.operatorfunc = "v:lua.require'dios.ops'.contar"
    return 'g@'
  end
  local tipos = { char = 'v', line = 'V', block = vim.keycode('<C-v>') }
  local trozos = vim.fn.getregion(vim.fn.getpos("'["), vim.fn.getpos("']"), { type = tipos[kind] })
  local texto = table.concat(trozos, '\n')
  local palabras = select(2, texto:gsub('%S+', ''))
  vim.notify(('%d líneas, %d palabras, %d bytes'):format(#trozos, palabras, #texto))
end

El tipo block merece atención aparte. Con una selección rectangular, las marcas de corchete señalan esquinas opuestas, no principio y fin de un texto continuo, y getregion devuelve una lista con un fragmento por línea. Si tu operador no tiene sentido en bloque, lo honesto es detectarlo y avisar en lugar de producir un resultado silenciosamente incorrecto.

La repetición sale gratis

Aquí está el dividendo que justifica todo el rodeo. Cuando Neovim ejecuta un g@, registra la secuencia completa —operador más movimiento— en el mecanismo de repetición. Eso significa que . vuelve a aplicar tu operador con el mismo movimiento, y que 3. lo repite tres veces, sin que hayas escrito una línea de código para ello. Un mapeo corriente que llamase directamente a tu función perdería esa propiedad y necesitaría muletas externas.

La segunda propiedad heredada es la composición con conteos y con toda la gramática. Como Neovim resuelve el movimiento antes de llamarte, tu operador funciona automáticamente con 2j, con ap, con i(, con t, y con cualquier objeto de texto que instale un plugin después de que tú escribieras el operador. No hay acoplamiento: tú declaras el verbo, otros declaran los complementos, y la gramática los combina.