nvim-surround

Project Introduction: nvim-surround

nvim-surround is a powerful Neovim plugin designed to enhance text editing by allowing users to manipulate "surrounds" or text pairs with style and ease. This plugin offers a variety of features that provide users with intuitive and efficient ways to handle text surrounds in their code or documents.

Features

nvim-surround comes packed with a suite of features aimed at improving the editing experience:

• Add/Delete/Change Surrounding Pairs: Users can quickly add, delete, or change surrounding pairs of text. This works seamlessly with function calls and HTML tags.
• Dot-Repeat Capability: Users can repeat the previous actions effortlessly using the dot-repeat command.
• Buffer-Local Mappings and Surrounds: It allows users to set specific mappings and surrounds at a buffer level.
• Nearest Surrounding Pair Navigation: Users can jump directly to the nearest surrounding pair for quick modifications.
• Single Character Alias: Simplify text-object manipulation by using single characters as aliases for multiple objects. For instance, the character q can represent a variety of quote marks, allowing efficient transformations.
• User-Dependent Powerful Pairs: Users have the flexibility to work with surrounding pairs that depend on input, making it versatile for various editing scenarios.
• Custom Surrounds Modifications: Supports first-class modifications using Vim motions, Lua patterns, and Tree-sitter nodes.
• Visual Feedback: Provides highlighting for selections to give users visual feedback while editing.

Requirements

To fully enjoy the features of nvim-surround, users need:

• Neovim 0.8+: This is a core requirement to run the plugin effectively.
• Recommended Enhancements:
  • nvim-treesitter: When installed, it allows users to surround and modify Tree-sitter nodes, besides the standard Vim motions and Lua patterns.
  • nvim-treesitter-textobjects: With this, Tree-sitter text-objects can define surrounds, making configuration more straightforward.

Installation

Installing nvim-surround is straightforward. It integrates with popular Neovim plugin managers like lazy.nvim and packer.nvim. Users simply need to add it to their configuration and call require("nvim-surround").setup() to initialize it.

For lazy.nvim:

{
    "kylechui/nvim-surround",
    version = "*", -- Stability recommended; omit for latest features
    event = "VeryLazy",
    config = function()
        require("nvim-surround").setup({
            -- Configuration can be set here
        })
    end
}

For packer.nvim:

use({
    "kylechui/nvim-surround",
    tag = "*", -- Stability recommended; omit for latest features
    config = function()
        require("nvim-surround").setup({
            -- Configuration can be set here
        })
    end
})

Usage

The plugin operates mainly through three core commands—add, delete, and change. These are executed using simple keymaps:

• Add: ys{motion}{char}
• Delete: ds{char}
• Change: cs{target}{replacement}

Examples include surrounding words with parentheses, altering HTML tags, or removing function calls in a snap. Detailed instructions are accessible via the usage documentation.

Configuration

Users are able to tailor nvim-surround to suit their workspace needs by modifying the default configuration. This is done by invoking require("nvim-surround").setup with desired options. More configuration options and details can be found in the plugin's extensive documentation.

Contributing

nvim-surround welcomes contributions from the community. Interested contributors can find guidelines in the project's contribution file.

Acknowledgments

nvim-surround is inspired by other similar projects, including vim-surround, mini.surround, and vim-sandwich. Users who appreciate this plugin are encouraged to give it a star on its repository to show support.