shell-stuff/nvim/lua/mapping.lua

-- ============================================================================
-- Configuração de Mapeamentos do Neovim em Lua
-- Referência: https://tuckerchapman.com/
-- ============================================================================

-- Realiza a inicialização da API do Neovim
local vim = vim

-- Tabela centralizada que armazena todos os mapeamentos organizados por modo
-- Cada modo contém mapeamentos com suas respectivas ações e opções
local Mapping = {
    -- ========================================================================
    -- MODO INSERT
    -- Mapeamentos utilizados quando se está inserindo texto no editor
    -- ========================================================================
    i = {
        -- Navegação de linhas: movimentos para início da linha
        -- Facilita o retorno ao início da linha sem sair do modo insert
        ["<C-a>"] = {
            "<ESC>^i",
            "Begin of line"
        },
        ["<C-b>"] = { "<ESC>^i", "Begin of line" },

        -- Inserir bloco de código de markdown
        -- Facilita a inserção de blocos de código com as backticks de markdown
        ["<F6>"] = { "```\n```\n", "Insert markdown code block" },

        -- Desabilitar teclas de seta para fortalecer o aprendizado de
        -- movimentos Vim
        --
        -- As teclas de seta (hjkl) são o padrão no Vim e investir em sua
        -- memorização
        --
        -- melhora significativamente a velocidade de edição a longo prazo
        ["<down>"] = {
            "<NOP>", "É uma abreviação de 'No Operation'.", { noremap = true }
        },
        ["<left>"] = {
            "<NOP>", "É uma abreviação de 'No Operation'.", { noremap = true }
        },
        ["<right>"] = {
            "<NOP>", "É uma abreviação de 'No Operation'.", { noremap = true }
        },
        ["<up>"] = {"<NOP>", "É uma abreviação de 'No Operation'.",
            { noremap = true }
        },
    },

    -- ========================================================================
    -- MODO NORMAL
    -- Mapeamentos utilizados no modo padrão de navegação e edição
    -- Agrupa mapeamentos para navegação entre splits, configuração e edição
    -- ========================================================================
    n = {
        -- Configurações de clipboard: comportamento de copiar, recortar e colar
        -- Acho que essas configurações servem para alterar o comportamento do
        -- copiar, recortar e colar
        -- ["gy"] = { "\"+ y", "Copy to clipboard" },
        -- ["gp"] = { "\"+ p", "Paste from clipboard" },
        -- ["x"] = { '"_ x', "Delete without copy" },
        -- ["X"] = { '"_ d', "Delete line without copy" },
        -- Deixei comentado pois estava modificando o comportamento padrão do
        -- vim e estava me atrapalhando.
        -- Essas configurações fazem com que x e X no modo normal e visual não
        -- copiem o texto para o registro padrão
        -- (usam o registro "black hole" "_). Pesquise depois com detalhes
        -- sobre registros no vim para entender melhor.

        -- Navegação entre janelas (splits)
        -- Facilita a movimentação entre múltiplas janelas abertas simultaneamente.
        -- Substitui as combinações padrão <C-w> + direção por atalhos mais diretos.
        ["<C-h>"] = { "<C-w>h", "Shortcuts for split navigation left" },
        ["<C-j>"] = { "<C-w>j", "Shortcuts for split navigation down" },
        ["<C-k>"] = { "<C-w>k", "Shortcuts for split navigation up" },
        ["<C-l>"] = { "<C-w>l", "Shortcuts for split navigation right" },

        -- Limpeza de highlights de busca
        -- Remove o destaque das buscas anteriores quando ESC é pressionado,
        -- mantendo a tela limpa e facilitando a concentração no código
        ["<ESC>"] = { "<cmd> noh <CR>", "Clear highlights" },

        -- Navegação de caracteres customizada: utiliza 'ç' para entrar em modo comando
        -- Permite usar o caractere específico do teclado português para acessar
        -- o modo de comando sem necessidade de combinações de teclas
        ["ç"] = { ":", "entra no modo de comando" },

        -- Alternância de números de linha e números relativos
        -- Alterna simultaneamente entre número absoluto e relativo (relativenumber),
        -- permitindo uma rápida alternância entre modos de navegação sem buscar uma linha específica
        ["<leader>n"] = { ":set number! relativenumber! <CR>", "toggle number" },

        -- Execução de arquivo de configuração atual
        -- Carrega novamente o arquivo aberto no editor, útil para testar
        -- mudanças em arquivos de configuração sem reiniciar o editor
        ["<leader>s"] = { "<cmd> source % <CR>", "source current file" },

        -- Salvamento rápido do buffer atual
        -- Salva o arquivo em edição com um atalho único, evitando múltiplas combinações
        ["<leader>w"] = { ":w<CR>", "Clear write current buffer - same up" },

        -- Recarga de todo o arquivo de configuração do Vim/Neovim
        -- Reaplica as definições de configuração sem necessidade de reiniciar,
        -- permitindo testes rápidos de mudanças na configuração principal
        ["<leader><leader>"] = { ":source $MYVIMRC<CR>", "reload vim/neovim config" },

        -- Selecionar todo o conteúdo do arquivo
        -- Mantém os jumps intactos ao selecionar tudo usando keepjumps
        ["<leader>a"] = { ":keepjumps normal! ggVG<CR>", "Select all" },

        -- Editar arquivo de configuração
        -- Abre o arquivo de configuração principal do Vim/Neovim para edição
        ["<leader>e"] = { "<cmd>edit $MYVIMRC<CR>", "Edit config file" },

        -- Sair de todos os buffers e fechar Neovim
        -- Fecha todas as janelas e sai do editor sem confirmação
        ["<leader>q"] = { "<cmd>quitall<CR>", "Exit vim" },

        -- Abrir terminal integrado
        -- Abre um terminal embutido dentro do Neovim para executar comandos
        ["<leader>t"] = { "<cmd>term<CR>", "Open terminal" },

        -- Buscar entre buffers abertos
        -- Lista os arquivos abertos permitindo navegação rápida entre eles
        ["<leader><space>"] = { "<cmd>files<CR>:buffer ", "Search open files" },

        -- Alternância da árvore de arquivos (NERDTree)
        -- Abre ou fecha a visão lateral contendo a estrutura de pastas e arquivos,
        -- permitindo navegação rápida entre diferentes partes do projeto
        -- ["<C-a>"] = { ":NERDTreeToggle<CR>", "open/close nerdtree" },
        -- ["<leader>t"] = { ":NERDTreeToggle<CR>", "open/close nerdtree" },

        -- Desabilitar teclas de seta com feedback ao usuário
        -- Quando uma tecla de seta é pressionada, exibe uma mensagem de erro encorajando
        -- o uso dos movimentos Vim (hjkl), reforçando a aquisição do hábito
        ['<down>'] = {
            function() vim.api.nvim_err_writeln("Umm, use j instead") end,
            { noremap = true }
        },
        ['<left>'] = {
            function() vim.api.nvim_err_writeln("Umm, use h instead") end,
            { noremap = true }
        },
        ['<right>'] = {
            function() vim.api.nvim_err_writeln("Umm, use l instead") end,
            { noremap = true }
        },
        ['<up>'] = {
            function() vim.api.nvim_err_writeln("Umm, use k instead") end,
            { noremap = true }
        },
    },

    -- ========================================================================
    -- MODO TERMINAL
    -- Mapeamentos utilizados quando se está em um terminal integrado no Neovim
    -- ========================================================================
    t = {
        -- Saída do modo terminal para modo normal
        -- Permite retornar ao modo normal de Vim/Neovim mesmo quando um shell
        -- está aberto, facilitando a navegação e edição sem fechar o terminal
        ["<C-x>"] = {
            vim.api.nvim_replace_termcodes("<C-\\><C-N>", true, true, true),
            "Escape terminal mode"
        },

        -- Sair do modo terminal com ESC
        -- Permite retornar ao modo normal de edição usando a tecla ESC
        ["<Esc>"] = {
            vim.api.nvim_replace_termcodes("<C-\\><C-N>", true, true, true),
            "Exit terminal mode"
        },
    },

    -- ========================================================================
    -- MODO VISUAL
    -- Mapeamentos utilizados quando texto está selecionado em modo visual
    -- ========================================================================
    v = {
        -- Movimentação vertical suave em seleções com quebra de linha
        -- Respeita quebras de linha visual (word wrap), movendo-se por linhas lógicas
        -- em vez de linhas físicas, útil quando o texto está dividido em múltiplas linhas visuais
        ["<Up>"] = {
            'v:count || mode(1)[0:1] == "no" ? "k" : "gk"', "Move up",
            opts = { expr = true }
        },
        ["<Down>"] = {
            'v:count || mode(1)[0:1] == "no" ? "j" : "gj"', "Move down",
            opts = { expr = true }
        },

        -- Indentação de blocos selecionados
        -- Mantém a seleção visual ativa após indentar, permitindo múltiplas
        -- indentações consecutivas sem necessidade de reselecionar o texto
        ["<"] = { "<gv", "Indent line" },
        [">"] = { ">gv", "Indent line" },
    },

    -- ========================================================================
    -- MODO VISUAL-BLOCK (seleção em bloco)
    -- Mapeamentos utilizados em seleções de bloco (Ctrl-V)
    -- ========================================================================
    x = {
        -- Movimentação vertical suave em blocos de seleção
        -- Respeita quebras de linha visuais, movendo-se naturalmente através
        -- de linhas envolvidas em word wrap
        ["j"] = {
            'v:count || mode(1)[0:1] == "no" ? "j" : "gj"', "Move down",
            opts = { expr = true }
        },
        ["k"] = {
            'v:count || mode(1)[0:1] == "no" ? "k" : "gk"', "Move up",
            opts = { expr = true }
        },

        -- Colamento sem consumir o conteúdo da seleção original
        -- Mantém o conteúdo anteriormente copiado intacto após colar sobre uma seleção,
        -- evitando a perda de dados quando se quer colar múltiplas vezes o mesmo conteúdo.
        -- Referência: https://vim.fandom.com/wiki/Replace_a_word_with_yanked_text#Alternative_mapping_for_paste
        ["p"] = {
            'p:let @+=@0<CR>:let @"=@0<CR>', "Dont copy replaced text",
            opts = { silent = true }
        },
    },
}
-- ============================================================================
-- APLICAÇÃO DOS MAPEAMENTOS
-- Percorre a tabela Mapping e registra todos os mapeamentos no Neovim
-- ============================================================================
-- Itera sobre cada modo (i, n, t, v, x) e seus respectivos mapeamentos
for modo, mapeamentos in pairs(Mapping) do
    -- Itera sobre cada tecla-ação dentro do modo atual
    for tecla, acao in pairs(mapeamentos) do
        local comando = acao[1]
        local descricao = acao[2]
        local opt_customizado = acao.opts ~= nil

        -- Registra o mapeamento com as opções customizadas ou padrão (noremap)
        -- noremap = true previne mapeamentos recursivos, evitando
        -- comportamentos inesperados
        if (opt_customizado)
        then
            vim.keymap.set(modo, tecla, comando, acao.opts)
        else
            vim.keymap.set(modo, tecla, comando, { noremap = true })
        end
    end
end

-- ============================================================================
-- DEFINIÇÃO DO MÓDULO
-- Exporta funções customizadas para serem utilizadas em mapeamentos e comandos
-- ============================================================================
local M = {}

-- Função utilitária para exibir "Hello World" no console
-- Utilizada para testes e demonstrações de integração entre mapeamentos e Lua
function M.PrintHelloWorld()
    print("Hello World")
end

-- ============================================================================
-- VARIÁVEIS GLOBAIS E COMMANDOS CUSTOMIZADOS
-- Define variáveis globais e comandos do Neovim para facilitar acesso
-- às funções
-- ============================================================================

-- Marca globalmente que o módulo de mapeamento foi carregado com sucesso
-- Permite que outros scripts verifiquem se este arquivo foi executado
_G.my_mapping_loaded = true

-- Cria um atalho <leader>ph para executar a função PrintHelloWorld
-- Permite invocar a função com um atalho de teclado no modo normal
vim.api.nvim_set_keymap(
    'n', '<leader>ph', ':lua require("mapping").PrintHelloWorld()<CR>',
    { noremap = true, silent = true }
)

-- Define um comando customizado 'PrtHello' que executa a função PrintHelloWorld
-- Permite executar a função digitando ':PrtHello' no modo de comando do Neovim
vim.api.nvim_create_user_command('PrtHello', M.PrintHelloWorld, {})

-- ============================================================================
-- EXPORTAÇÃO DO MÓDULO
-- Retorna o módulo para que ele possa ser utilizado em outros
-- arquivos de configuração
-- ============================================================================
return M