Serpl

serpl is a terminal user interface (TUI) application that allows users to search and replace keywords in an entire folder, similar to the functionality available in VS Code.

https://github.com/yassinebridi/serpl/assets/18403595/c63627da-7984-4e5f-b1e2-ff14a5d44453

Table of Contents

1. Features
2. Installation
   • Prerequisites
   • Steps
   • Binaries
   • OS Specific Installation
3. Usage
   • Basic Commands
   • Key Bindings
   • Configuration
4. Panes
   • Search Input
   • Replace Input
   • Search Results Pane
   • Preview Pane
5. Neovim Integration using toggleterm
6. License
7. Contributing

Features

• Search for keywords across an entire project folder.
• Replace keywords with options for preserving case.
• Interactive preview of search results.
• Keyboard navigation for efficient workflow.
• Configurable key bindings and search modes.

Installation and Update

Prerequisites

• Cargo installed on your system.
• ripgrep installed on your system.

Steps

1. Install the application using Cargo:

   cargo install serpl

2. Update the application using Cargo:

   cargo install serpl

3. Run the application:

   serpl

Binaries

Check the releases page for the latest binaries.

OS Specific Installation

Arch Linux

serpl can be installed from the official repositories using pacman:

pacman -S serpl

Usage

Basic Commands

• Start the application in the current directory:

  serpl

• Start the application and provide the project root path:

  serpl --project-root /path/to/project

Key Bindings

Default key bindings can be customized through the config.json file.

Default Key Bindings

Configuration

serpl uses a configuration file to manage key bindings and other settings. By default, the path to the configuration file can be found by running serpl --version. You can use various file formats for the configuration, such as JSON, JSON5, YAML, TOML, or INI.

Example Configurations

You can customize the key bindings by modifying the configuration file in the format of your choice.

Panes

Search Input

• Input field for entering search keywords.
• Toggle search modes (Simple, Match Case, Whole Word, Regex).

Replace Input

• Input field for entering replacement text.
• Toggle replace modes (Simple, Preserve Case).

Search Results Pane

• List of files with search results.
• Navigation to select and view files.
• Option to delete files from the search results.

Preview Pane

• Display of the selected file with highlighted search results.
• Navigation to view different matches within the file.
• Option to delete individual lines containing matches.

Neovim Integration using toggleterm

Check out the toggleterm.nvim plugin for Neovim, which provides a terminal that can be toggled with a key binding. Or you can use the following configuration, if you are using AstroNvim:

return {
  "akinsho/toggleterm.nvim",
  cmd = { "ToggleTerm", "TermExec" },
  dependencies = {
    {
      "AstroNvim/astrocore",
      opts = function(_, opts)
        local maps = opts.mappings
        local astro = require "astrocore"
        maps.n["<Leader>t"] = vim.tbl_get(opts, "_map_sections", "t")

        local serpl = {
          callback = function()
            astro.toggle_term_cmd "serpl"
          end,
          desc = "ToggleTerm serpl",
        }
        maps.n["<Leader>sr"] = { serpl.callback, desc = serpl.desc }

        maps.n["<Leader>tf"] = { "<Cmd>ToggleTerm direction=float<CR>", desc = "ToggleTerm float" }
        maps.n["<Leader>th"] = { "<Cmd>ToggleTerm size=10 direction=horizontal<CR>", desc = "ToggleTerm horizontal split" }
        maps.n["<Leader>tv"] = { "<Cmd>ToggleTerm size=80 direction=vertical<CR>", desc = "ToggleTerm vertical split" }
        maps.n["<F7>"] = { '<Cmd>execute v:count . "ToggleTerm"<CR>', desc = "Toggle terminal" }
        maps.t["<F7>"] = { "<Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.i["<F7>"] = { "<Esc><Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.n["<C-'>"] = { '<Cmd>execute v:count . "ToggleTerm"<CR>', desc = "Toggle terminal" }
        maps.t["<C-'>"] = { "<Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.i["<C-'>"] = { "<Esc><Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
      end,
    },
  },
  opts = {
    highlights = {
      Normal = { link = "Normal" },
      NormalNC = { link = "NormalNC" },
      NormalFloat = { link = "NormalFloat" },
      FloatBorder = { link = "FloatBorder" },
      StatusLine = { link = "StatusLine" },
      StatusLineNC = { link = "StatusLineNC" },
      WinBar = { link = "WinBar" },
      WinBarNC = { link = "WinBarNC" },
    },
    size = 10,
    ---@param t Terminal
    on_create = function(t)
      vim.opt_local.foldcolumn = "0"
      vim.opt_local.signcolumn = "no"
      if t.hidden then
        local toggle = function() t:toggle() end
        vim.keymap.set({ "n", "t", "i" }, "<C-'>", toggle, { desc = "Toggle terminal", buffer = t.bufnr })
        vim.keymap.set({ "n", "t", "i" }, "<F7>", toggle, { desc = "Toggle terminal", buffer = t.bufnr })
      end
    end,
    shading_factor = 2,
    direction = "float",
    float_opts = { border = "rounded" },
  },
}

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

(WIP)