README.md

Script de Debug para Shell no Neovim

Descrição

Este script Lua para Neovim fornece uma funcionalidade para gerar automaticamente comandos echo de debug para variáveis shell em uma seleção visual. Ele é específico para arquivos shell (.sh) e é carregado como um plugin after/ftplugin.

Funcionalidades

• Extrai nomes de variáveis de atribuições em shell script
• Gera comandos echo formatados para debug
• Insere os comandos automaticamente após a seleção
• Suporte a ranges visuais através de comando e mapeamento de teclas

Componentes

Função extract_variables(lines)

Parâmetros:

• lines (table): Lista de strings contendo linhas de código shell

Retorno:

• Table com nomes de variáveis encontradas

Descrição: Extrai nomes de variáveis de linhas que seguem o padrão VARIAVEL=valor. Busca por linhas que começam com optional whitespace, seguido por caracteres maiúsculos, underscores ou dígitos, seguidos por =.

Função generate_shell_echoes_range(line1, line2)

Parâmetros:

• line1 (number): Linha inicial do range (1-based)
• line2 (number): Linha final do range (1-based)

Descrição:

• Processa as linhas no range especificado
• Extrai variáveis usando extract_variables
• Gera blocos de debug formatados com comandos echo
• Insere o bloco após a última linha do range

Comando de Usuário ShellEcho

Sintaxe:

:'<,'>ShellEcho

Características:

• Aceita range (obrigatório)
• Funciona em modo visual com :'<,'>
• Processa apenas a seleção visual atual

Mapeamento de Teclas

Tecla: <F2> no modo visual

Ação: Executa :'<,'>ShellEcho<CR>

Descrição: Gera echos de debug para variáveis na seleção visual atual.

Comportamento de Saída

O script gera um bloco de debug no formato:

###############################################
# DEBUG                                       #
###############################################
echo VARIAVEL1 = ${VARIAVEL1}
echo VARIAVEL2 = ${VARIAVEL2}

Exemplo de Uso

Código original (selecionado visualmente):

NAME="John"
AGE=30
CITY="New York"

Após pressionar <F2> no modo visual:

NAME="John"
AGE=30
CITY="New York"
###############################################
# DEBUG                                       #
###############################################
echo NAME = ${NAME}
echo AGE = ${AGE}
echo CITY = ${CITY}

Arquivo e Localização

Arquivo: after/ftplugin/sh.lua

Propósito: Plugin específico para arquivos shell que carrega após os ftplugins padrão.

Dependências

• Neovim com API Lua habilitada
• Buffer contendo código shell

Notas Técnicas

Tratamento de Range

• Usa a abordagem recomendada do Vim com opts.line1 e opts.line2
• Não depende de marks ('<, '>) diretamente, evitando problemas de contexto
• O range é tratado automaticamente pelo Neovim quando usando :'<,'>ShellEcho

Padrão de Busca de Variáveis

• Busca por ^%s*([%u_%d]+)%s*=
• Encontra variáveis que começam no início da linha (com whitespace opcional)
• Aceita letras maiúsculas, números e underscores
• Requer sinal de = após o nome da variável

Mensagens de Feedback

• "Nenhuma linha no range." - Quando a seleção está vazia
• "Nenhuma variável encontrada." - Quando não há atribuições de variáveis no range

Limitações

• Só detecta variáveis em linhas de atribuição simples
• Variáveis devem estar em maiúsculas (convenção shell)
• Não detecta variáveis em comandos complexos ou multi-linha

Solução de Problemas

Se o mapeamento não funcionar:

1. Certifique-se de estar no modo visual
2. Verifique se há variáveis no padrão correto na seleção
3. Use o comando manualmente: :'<,'>ShellEcho

Este script substitui abordagens problemáticas baseadas em marks, oferecendo uma solução robusta e integrada com o ecossistema Vim.

sh.lua

-- after/ftplugin/sh.lua

local function extract_variables(lines)
	local vars = {}
	for _, line in ipairs(lines) do
		local var = line:match("^%s*([%u_%d]+)%s*=")
		if var then
			table.insert(vars, var)
		end
	end
	return vars
end

local function generate_shell_echoes_range(line1, line2)
	-- line1, line2 são 1-based e vêm do próprio Vim (não de '<,'>)
	local start_idx = line1 - 1
	local end_idx = line2 -- exclusivo

	local lines = vim.api.nvim_buf_get_lines(0, start_idx, end_idx, false)
	if not lines or #lines == 0 then
		print("Nenhuma linha no range.")
		return
	end

	local vars = extract_variables(lines)
	if #vars == 0 then
		print("Nenhuma variável encontrada.")
		return
	end

	local echo_lines = {
		"###############################################",
		"# DEBUG                                       #",
		"###############################################",
	}

	for _, v in ipairs(vars) do
		table.insert(echo_lines, string.format("echo %s = ${%s}", v, v))
	end

	-- Inserir depois da última linha do range
	local insert_pos = line2 -- 1-based -> posição de inserção 0-based
	vim.api.nvim_buf_set_lines(0, insert_pos, insert_pos, false, echo_lines)
end

-- Comando com range
vim.api.nvim_create_user_command("ShellEcho", function(opts)
	generate_shell_echoes_range(opts.line1, opts.line2)
end, { range = true })

vim.keymap.set(
	"v",
	"<F2>",
	[[:'<,'>ShellEcho<CR>]],
	{ noremap = true, silent = true, desc = "Gerar echos de variáveis shell" }
)