ContextQMD
Back to Spacevim

nvim-surround

bundle/nvim-surround/README.md

2.4.04.0 KB
Original Source

nvim-surround

Surround selections, stylishly :sunglasses:

<div align="center"> <video src="https://user-images.githubusercontent.com/48545987/178679494-c7d58bdd-d8ca-4802-a01c-a9444b8b882f.mp4" type="video/mp4"></video> </div>

:sparkles: Features

  • Add/delete/change surrounding pairs
    • Function calls and HTML tags out-of-the-box
  • Dot-repeat previous actions
  • Set buffer-local mappings and surrounds
  • Jump to the nearest surrounding pair for modification
  • Use a single character as an alias for several text-objects
    • E.g. q is aliased to <code>`,',"</code>, so <code>csqb</code> replaces the nearest set of quotes with parentheses
  • Surround using powerful pairs that depend on user input
  • Modify custom surrounds
    • First-class support for Vim motions, Lua patterns, and Tree-sitter nodes
  • Highlight selections for visual feedback

:lock: Requirements

  • Neovim 0.8+
  • [Recommended] If nvim-treesitter is installed, then Tree-sitter nodes may be surrounded and modified, in addition to just Vim motions and Lua patterns
  • [Recommended] If nvim-treesitter-textobjects is installed, then Tree-sitter text-objects can be used to define surrounds, simplifying configuration

:package: Installation

Install this plugin using your favorite plugin manager, and then call require("nvim-surround").setup().

lazy.nvim

lua
{
    "kylechui/nvim-surround",
    version = "*", -- Use for stability; omit to use `main` branch for the latest features
    event = "VeryLazy",
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
}

packer.nvim

lua
use({
    "kylechui/nvim-surround",
    tag = "*", -- Use for stability; omit to use `main` branch for the latest features
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
})

:rocket: Usage

The three "core" operations of add/delete/change can be done with the keymaps ys{motion}{char}, ds{char}, and cs{target}{replacement}, respectively. For the following examples, * will denote the cursor position:

help
    Old text                    Command         New text
--------------------------------------------------------------------------------
    surr*ound_words             ysiw)           (surround_words)
    *make strings               ys$"            "make strings"
    [delete ar*ound me!]        ds]             delete around me!
    remove <b>HTML t*ags</b>    dst             remove HTML tags
    'change quot*es'            cs'"            "change quotes"
    <b>or tag* types</b>        csth1<CR>       <h1>or tag types</h1>
    delete(functi*on calls)     dsf             function calls

Detailed information on how to use this plugin can be found in :h nvim-surround.usage.

:gear: Configuration

The default configuration is found here. Simply call require("nvim-surround").setup or require("nvim-surround").buffer_setup with the desired options.

More information on how to configure this plugin can be found in :h nvim-surround.configuration.

Contributing

See the contributing file.

Shoutouts