mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-02-03 06:50:05 +08:00
112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
# 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+](https://github.com/neovim/neovim/releases)
|
|
- \[Recommended] If
|
|
[nvim-treesitter](https://github.com/nvim-treesitter/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](https://github.com/nvim-treesitter/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](https://github.com/folke/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](https://github.com/wbthomason/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`](https://github.com/kylechui/nvim-surround/blob/main/doc/nvim-surround.txt).
|
|
|
|
## :gear: Configuration
|
|
|
|
The default configuration is found
|
|
[here](https://github.com/kylechui/nvim-surround/blob/main/lua/nvim-surround/config.lua).
|
|
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`](https://github.com/kylechui/nvim-surround/blob/main/doc/nvim-surround.txt).
|
|
|
|
## Contributing
|
|
|
|
See
|
|
[the contributing file](https://github.com/kylechui/nvim-surround/blob/main/CONTRIBUTING.md).
|
|
|
|
## Shoutouts
|
|
|
|
- [vim-surround](https://github.com/tpope/vim-surround)
|
|
- [mini.surround](https://github.com/echasnovski/mini.surround)
|
|
- [vim-sandwich](https://github.com/machakann/vim-sandwich)
|
|
- Like this project? Give it a :star: to show your support!
|