Surrounds Showcase

[kylechui]

Hey everybody! With the release of function-evaluated surrounds, I thought I might create a thread where people can share custom surrounds that they think others might benefit from. If this goes well, I might also create a page in the Wiki for the best ones. If you'd like to contribute, I ask that you please format your responses as a GIF/video embed that shows off your surround, with the corresponding setup code hidden inside a details drop down menu. Thanks to everybody that makes a submission!

Submission Template

## [TITLE GOES HERE]

<!-- You can choose to upload a video/GIF -->
<video src="[VIDEO URL GOES HERE]">
<img src="[GIF URL GOES HERE]">
<!-- Or describe the buffer/cursor position *before* the command, and the buffer contents *after* -->
```
[DESCRIPTION GOES HERE]
```

<details>
<summary>Implementation</summary>

```lua
[CODE GOES HERE]
```

</details>

[kylechui]

Custom function surrounds per code block in a Markdown file

treesitter_demo_1.mp4

Implementation

local surr_utils = require("nvim-surround.config")
local ts_utils = require("nvim-treesitter.ts_utils")
local query = vim.treesitter.query

require("nvim-surround").buffer_setup({
    surrounds = {
        ["f"] = {
            add = function()
                local cur = ts_utils.get_node_at_cursor(0, true)
                while cur and cur:type() ~= "fenced_code_block" do
                    cur = cur:parent()
                end

                local language = nil
                if cur then
                    for child_node in cur:iter_children() do
                        if child_node:type() == "info_string" then
                            language = query.get_node_text(child_node:child(0), 0)
                        end
                    end
                end

                if language == "cpp" then
                    local input = surr_utils.get_input("Enter a function name: ")
                    if input then
                        return {
                            { "auto " .. input .. " = [](" },
                            {
                                "){",
                                "    return 0;",
                                "}",
                            },
                        }
                    end
                elseif language == "lua" then
                    local input = surr_utils.get_input("Enter a function name: ")
                    if input then
                        return {
                            { "local " .. input .. " = function(" },
                            {
                                ")",
                                "    return nil",
                                "end",
                            },
                        }
                    end
                elseif language == "python" then
                    local input = surr_utils.get_input("Enter a function name: ")
                    if input then
                        return {
                            { input .. " = lambda " },
                            {
                                ":",
                                "    return NULL",
                            },
                        }
                    end
                end
                return { { "" }, { "" } }
            end,
        },
    },
})

[kylechui]

Surround markdown link title, using clipboard contents

@andrewferrier I got inspired by your Markdown surround, and came up with this instead

markdown_link_demo.mp4

Implementation

require("nvim-surround").buffer_setup({
    surrounds = {
        ["l"] = {
            add = function()
                local clipboard = vim.fn.getreg("+"):gsub("\n", "")
                return {
                    { "[" },
                    { "](" .. clipboard .. ")" },
                }
            end,
            find = "%b[]%b()",
            delete = "^(%[)().-(%]%b())()$",
            change = {
                target = "^()()%b[]%((.-)()%)$",
                replacement = function()
                    local clipboard = vim.fn.getreg("+"):gsub("\n", "")
                    return {
                        { "" },
                        { clipboard },
                    }
                end,
            },
        },
    },
})

[kylechui]

@Kiran-Raj-Dev From :h nvim-surround.config.surrounds:

    find: ~
        A function that returns the "parent selection" for a surrounding pair.
        The selection returned should contain the surrounding pair and little
        else, as it is used by the `delete` and `change` keys to determine
        what to modify.

        For convenience, this key can also take a string as a value, which is
        then interpreted as a Lua pattern that represents the selection. For
        example, HTML tags are found via the `at` text-object:
>
        local config = require("nvim-surround.config")
        ["t"] = {
            find = function()
                return config.get_selection({ textobject = "t" })
            end,
        }
<
        See |nvim-surround.config.helpers| for information on how to utilize
        the provided helper functions.

[ad-chaos]

Ah! Right, the way I was searching for it was that, there were help texts for
:h nvim-surround.add
:h nvim-surround.change
:h nvim-surround.delete
but none, for :h nvim-surround.find so assumed that it was a new feature that wasn't documented.

[kylechui]

Oops, completely forgot to add that tag 😅; do you mind opening up an issue for that so I don't forget? Thanks!

Edit: Oh wait actually this is just how my docs are (poorly) organized. I originally wanted add/delete/change to just be basic introduction to the plugin, but then those names overlapped with actual configuration options, etc. I see that help tags are probably more useful than I had originally thought; I'll try to think of a better way to organize the docs such that information is more easily found.

[ssiccha]

For me the video preview doesn't show anymore. Do you have an idea what went wrong?

[kylechui]

@ssiccha I would try refreshing the page a few times? I'm not entirely sure why it sometimes does that on GitHub

[swarn]

Basic LaTeX

This isn't doing anything complex enough to be interesting, but it was the first thing I wanted.

% Before
Foo

% After command: ysiwctextit
\textit{Foo}

% Before
Bar

% After command: VSecentering
\begin{centering}
    Bar
\end{centering}

Note that this implementation only adds commands and environments; the excellent vimtex plugin already has dse, dsc, cse, and csc mappings, though it would be interesting to add them here, as well.

Implementation

require("nvim-surround").buffer_setup {
  surrounds = {
    ["c"] = {
      add = function()
        local cmd = require("nvim-surround.config").get_input "Command: "
        return { { "\\" .. cmd .. "{" }, { "}" } }
      end,
    },
    ["e"] = {
      add = function()
        local env = require("nvim-surround.config").get_input "Environment: "
        return { { "\\begin{" .. env .. "}" }, { "\\end{" .. env .. "}" } }
      end,
    },
  },
}

[kylechui]

I think text-based should be fine; I didn't consider it as an option until now. Since your surround is "cursor-agnostic", that also isn't an issue. Perhaps for more complex surrounds with more text in the buffer, defining cursor location would be necessary as well. I'll update the template and thanks for the submission!

Edit: Template has been updated

[rhelmstedter]

I use licecap to create gifs and keycastr to display keystrokes.

[andrewferrier]

Nice! I'm using this!

[olimorris]

This is awesome. Personally prefer text to a GIF as it can be really hard to follow

[swarn]

Updated for 1.0.

[kylechui]

Print Statements

Very often I find myself writing print debug statements, but find it very tedious to add them in manually when I've already copy-pasted what I want to print from the line above. With this surround and yssp, printing is a breeze. This can also be extended to other languages, e.g. { "cout << ", " << endl;" } for C++.

-- Before modification
arg1, arg2
-- Type `yssp`
vim.pretty_print(arg1, arg2)
-- Type `dsp`
arg1, arg2 

Edit: C++ demo below, it takes into account whether or not your file includes using namespace std;, and uses that to determine whether or not your print surround should contain std::

cpp_print_demo.mp4

Implementation

-- ftplugin/lua.lua
require("nvim-surround").buffer_setup({
    surrounds = {
        ["p"] = {
            add = { "vim.pretty_print(", ")" },
            find = "vim%.pretty_print%b()",
            delete = "^(vim%.pretty_print%()().-(%))()$",
            change = {
                target = "^(vim%.pretty_print%()().-(%))()$",
            },
        },
    }
})
-- ftplugin/cpp.lua
require("nvim-surround").buffer_setup({
    surrounds = {
        ["p"] = {
            add = function()
                for _, line in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
                    if line == "using namespace std;" then
                        return { { "cout << " }, { " << endl;" } }
                    end
                end
                return { { "std::cout << " }, { " << std::endl;" } }
            end,
            find = function()
                local config = require("nvim-surround.config")
                for _, line in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
                    if line == "using namespace std;" then
                        return config.get_selection({ pattern = "cout << .- << endl;" })
                    end
                end
                return config.get_selection({ pattern = "std::cout << .- << std::endl;" })
            end,
            delete = function()
                local config = require("nvim-surround.config")
                for _, line in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
                    if line == "using namespace std;" then
                        return config.get_selections({
                            char = "p",
                            pattern = "^(cout << )().-( << endl;)()$",
                        })
                    end
                end
                return config.get_selections({
                    char = "p",
                    pattern = "^(std::cout << )().-( << std::endl;)()$",
                })
            end,
        },
    },
})

[ryan-heslin]

Object Keys

Demonstration

Many languages (Python, R, and Lua, for example) feature complex data structures that consist of elements that can be accessed by name using this syntax:

object["element"]

Often, I find I want to turn an object in the global environment into an element of a containing object, or vice versa. This mapping provides a simple way to do that. It prompts the user for the name of the containing object, then turns the text object into an element reference for it. Deletion removes everything but the element name. Right now it won't work for a key that uses quote marks, (e.g., foo['"bar'], since I don't know an easy way of matching a balanced string and splitting the match across multiple capture groups.

Edited to cover element references from object names (e.g., foo[bar]) using the "K" surround key.

Implementation

require("nvim-surround").setup({
    surrounds = {
        ["k"] = {
            add = quoted_surround,
            find = quoted_pattern,
            delete = quoted_pattern,
            change = {
                target = quoted_pattern,
            },
        },
        ["K"] = {
            add = unquoted_surround,
            find = unquoted_pattern,
            delete = unquoted_pattern,
            change = {
                target = unquoted_pattern,
            },
        },
    },
})

[chrisgrieser]

Delete Surrounding Function

So after seeing the example of surrounding a function, I thought why not write a custom surround deletion that removes the surrounding function syntax. Should be useful for refactoring.

Implemented for lua, but you can add more languages by adding filetype-specific lua patterns for delete.

-- Before modification
function demo()
  print("test")
end

-- Type `dsf`
print("test")

Implementation

-- requires treesitter-textobj plugin & treesitter
require("nvim-treesitter.configs").setup {
	textobjects = {
		select = {
			keymaps = {
				["af"] = "@function.outer",
			},
		}
	}
}

require("nvim-surround").setup {
	surrounds = {
		["f"] = {
			find = function()
				return require("nvim-surround.config").get_selection {motion = "af"}
			end,
			delete = function()
				local ft = bo.filetype
				local patt
				if ft == "lua" then
					patt = "^(.-function.-%b())().*(end)()$"
				else
					vim.notify("No function-surround defined for " .. ft)
					patt = "()()()()"
				end
				return require("nvim-surround.config").get_selections {
					char = "f",
					pattern = patt,
				}
			end,
	}
}

[ariel-frischer]

Replaced bo.filetype with vim.bo.filetype to get it running.

[j-hui]

LaTeX commands and environments

This implementation builds on @swarn 's, supporting replacement and deletion for LaTeX commands and environments. It supports options (e.g., \cmd[options]{contents} and \begin{env}[options] contents \end{env}), and makes use of Treesitter when available.

(I know lervag/vimtex already provides csc and cse etc., but I didn't want to use it for only this feature.)

The mnemonic is:

• c command
• C command with options
• e environment
• E environment with options

Note that some commands (e.g., ysE) will prompt you for both the command/environment name and the options.

Here's just some basic examples that summarizes how I use the changing and deletion commands:

\mycmd{change the surrounding command to something else, then delete it}
% cscothercmd<CR>
\othercmd{change the surrounding command to something else, then delete it}
% dsc
change the surrounding command to something else, then delete it

\mycmd[myopts]{change the surrounding command and options to something else, then delete them}
% csCothercmd<CR>otheropts<CR>
\othercmd[otheropts]{change the surrounding command and options to something else, then delete them}
% dsC
change the surrounding command and options to something else, then delete them

\begin{myenv}[myopts]
    Change the surrounding environment
    Change the surrounding options
    Delete the surrounding environment and its options
\end{myenv}
% cseotherenv<CR>
\begin{otherenv}[myopts]
    Change the surrounding environment
    Change the surrounding options
    Delete the surrounding environment and its options
\end{otherenv}
% csEotheropts<CR>
\begin{otherenv}[otheropts]
    Change the surrounding environment
    Change the surrounding options
    Delete the surrounding environment and its options
\end{otherenv}
% dsE

Change the surrounding environment
Change the surrounding options
Delete the surrounding environment and its options

Options are actually kind of fussy to handle, so there's some quirks and inconsistencies between commands and environments when it comes to dealing with options:

• For replacing commands, csC and csc only work on commands with and without options, respectively. e.g., using csc on a command with options is a nop.
• For replacing environments, csE and cse will both work on environments with options; the former will replace only the options, while the latter will replace only the environment name. Only the latter will work on environments without options.
• For deleting commands, dsC and dsc only work on command with and without options, respectively.
• For deleting environments, dsE only works on environments with options. dse works on environments both with and without options, but it won't delete those options for you (which is probably not what you want).

I documented these edge cases in the following examples:

More commands examples

surround-this-with-command
% ysiWcmycmd<CR>
\mycmd{surround-this-with-command}

surround-this-with-command-and-options
% ysiWCmycmd<CR>myopts<CR>
\mycmd[myopts]{surround-this-with-command-and-options}

\mycmd{change the surrounding command to something else, then delete it}
% cscothercmd<CR>
\othercmd{change the surrounding command to something else, then delete it}
% dsc
change the surrounding command to something else, then delete it

\mycmd[myopts]{change the surrounding command and options to something else, then delete them}
% csCothercmd<CR>otheropts<CR>
\othercmd[otheropts]{change the surrounding command and options to something else, then delete them}
% dsC
change the surrounding command and options to something else, then delete them

\outer[opts]{\inner{change the outer (with opts), delete the inner (no opts)}}
% csCmycmd<CR>myopts<CR>
\mycmd[myopts]{\inner{change the outer (with opts), delete the inner (no opts)}}
% dsc
\mycmd[myopts]{change the outer (with opts), delete the inner (no opts)}

\outer[opts]{\inner{change the inner (no opts), delete the outer (with opts)}}
% cscmycmd<CR>
\outer[opts]{\mycmd{change the inner (no opts), delete the outer (with opts)}}
% dsC
\mycmd{change the inner (no opts), delete the outer (with opts)}

\outer{\inner[opts]{change the outer (no opts), delete the inner (with opts)}}
% cscmycmd<CR>
\mycmd{\inner[opts]{change the outer (no opts), delete the inner (with opts)}}
% dsC
\mycmd{change the outer (no opts), delete the inner (with opts)}

\outer{\inner[opts]{change the inner (with opts), delete the outer (no opts)}}
% csCmycmd<CR>myopts<CR>
\outer{\mycmd[myopts]{change the inner (with opts), delete the outer (no opts)}}
% dsc
\mycmd[myopts]{change the inner (with opts), delete the outer (no opts)}

More environments examples

surround-this-with-environment
% ysiWemyenv<CR>
\begin{myenv}surround-this-with-environment\end{myenv}

surround-this-with-environment-and-options
% ysiWEmyenv<CR>myopts<CR>
\begin{myenv}[myopts]surround-this-with-environment-and-options\end{myenv}

\begin{myenv}
    Change the surrounding environment to something else, then delete it
\end{myenv}
% cseotherenv<CR>
\begin{otherenv}
    Change the surrounding environment to something else, then delete it
\end{otherenv}
% dse

Change the surrounding environment to something else, then delete it


\begin{myenv}[opts]
    When the surrounding environment has options:
    - cse only changes the environment
    - dse does not delete the options (!!), only begin-end pair
\end{myenv}
% cseotherenv<CR>
\begin{otherenv}[opts]
    When the surrounding environment has options:
    - cse only changes the environment
    - dse does not delete the options (!!), only begin-end pair
\end{otherenv}
% dse
[opts]
When the surrounding environment has options:
- cse only changes the environment
- dse does not delete the options (!!), only begin-end pair


\begin{myenv}[opts]
    When the surrounding environment has options:
    - csE only changes the options
    - dsE deletes both begin-end pair and its options
\end{myenv}
% csEmyopts<CR>
\begin{myenv}[myopts]
    When the surrounding environment has options:
    - csE only changes the options
    - dsE deletes both begin-end pair and its options
\end{myenv}
% dsE

When the surrounding environment has options:
- csE only changes the options
- dsE deletes both begin-end pair and its options


\begin{myenv}
    When the surrounding environment does not have options,
    csE and dsE do not do anything
\end{myenv}
% csE
\begin{myenv}
    When the surrounding environment does not have options,
    csE and dsE do not do anything
\end{myenv}
% dsE
\begin{myenv}
    When the surrounding environment does not have options,
    csE and dsE do not do anything
\end{myenv}

Implementation

local function tex_find_environment()
  local cfg = require("nvim-surround.config")
  if vim.g.loaded_nvim_treesitter then
    local selection = cfg.get_selection {
      node = "generic_environment",
      -- query = {
      --   capture = "@block.outer",
      --   type = "textobjects",
      -- }
      -- NOTE: ^query doesn't seem to work very reliably with LaTeX environments
    }
    if selection then
      return selection
    end
  end
  return cfg.get_selection [[\begin%b{}.-\end%b{}]]
  -- NOTE: ^this does not correctly handle \begin{}-\end{} pairs in all cases
  --        (hence we use treesitter if available)
end

local tex_opts = {
  surrounds = {
    ["c"] = {
      add = function()
        local cfg = require("nvim-surround.config")
        local cmd = cfg.get_input("Command: ")
        return { { "\\" .. cmd .. "{" }, { "}" } }
      end,
      find = [=[\[^\{}%[%]]-%b{}]=],
      delete = [[^(\[^\{}]-{)().-(})()$]],
      change = {
        target = [[^\([^\{}]-)()%b{}()()$]],
        replacement = function()
          local cfg = require("nvim-surround.config")
          local cmd = cfg.get_input("Command: ")
          return { { cmd }, { "" } }
        end
      },
    },
    ["C"] = {
      add = function()
        local cfg = require("nvim-surround.config")
        local cmd, opts = cfg.get_input("Command: "), cfg.get_input("Options: ")
        return { { "\\" .. cmd .. "[" .. opts .. "]{" }, { "}" } }
      end,
      find = [[\[^\{}]-%b[]%b{}]],
      delete = [[^(\[^\{}]-%b[]{)().-(})()$]],
      change = {
        target = [[^\([^\{}]-)()%[(.*)()%]%b{}$]],
        replacement = function()
          local cfg = require("nvim-surround.config")
          local cmd, opts = cfg.get_input("Command: "), cfg.get_input("Options: ")
          return { { cmd }, { opts } }
        end
      },
    },
    ["e"] = {
      add = function()
        local cfg = require("nvim-surround.config")
        local env = cfg.get_input("Environment: ")
        return { { "\\begin{" .. env .. "}" }, { "\\end{" .. env .. "}" } }
      end,
      find = tex_find_environment,
      delete = [[^(\begin%b{})().*(\end%b{})()$]],
      change = {
        target = [[^\begin{(.-)()%}.*\end{(.-)()}$]],
        replacement = function()
          local env = require("nvim-surround.config").get_input("Environment: ")
          return { { env }, { env } }
        end,
      }
    },
    ["E"] = {
      add = function()
        local cfg = require("nvim-surround.config")
        local env, opts = cfg.get_input("Environment: "), cfg.get_input("Options: ")
        return { { "\\begin{" .. env .. "}[" .. opts .. "]" }, { "\\end{" .. env .. "}" } }
      end,
      find = tex_find_environment,
      delete = [[^(\begin%b{}%b[])().*(\end%b{})()$]],
      change = {
        target = [[^\begin%b{}%[(.-)()()()%].*\end%b{}$]],
        replacement = function()
          local cfg = require("nvim-surround.config")
          local env = cfg.get_input("Environment options: ")
          return { { env }, { "" } }
        end,
      }
    },
  },
}

-- Key is filetype, value is the options table to be passed to require("nvim-surround").buffer_setup()
local ft_opts = {
  tex = tex_opts,
  plaintex = tex_opts,
}

[mscott99]

I was looking for something like this.

[willdavidow]

JavaScript String Interpolation Wrapper

This surround supports adding interpolation surrounds to words/visual selections and swaps the surrounding string to a template string if necessary.

Example: Change surrounding string and interpolate current word

console.log('some string with a variable');
console.log("some string with a variable");

while hovering the word variable in the two lines (above), and assuming you're using the default plugin keybindings: the result of running the command ysiws would produce:

console.log(`some string with a ${variable}`);

This will also work if the string is already wrapped with the ` character, or not wrapped in a string at all.

If the word is not wrapped in a string at all, it will wrap the immediate word with both ` and ${variable}.

so, this:

console.log(variable);

would become this:

console.log(`${variable}`);

Planning on extending to also delete interpolated variables and also (maybe?) swap back to a regular string at that point, but this is what I'm finding useful right now and wanted to share.

Implementation

surrounds = {
	["s"] = {
		add = function()
			local ts_utils = require("nvim-treesitter.ts_utils")
			local cur = ts_utils.get_node_at_cursor(0, true)
			local language = vim.bo.filetype
			local is_jsy = (
				language == "javascript"
				or language == "javascriptreact"
				or language == "typescript"
				or language == "typescriptreact"
			)

			if is_jsy then
				local cur_type = cur:type()
				local interpolation_surround = { { "${" }, { "}" } }
				if cur and (cur_type == "string" or cur_type == "string_fragment") then
					vim.cmd.normal("csq`")
					return interpolation_surround
				elseif cur and cur_type == "template_string" then
					return interpolation_surround
				else
					return { { "`${" }, { "}`" } }
				end
			end
		end,
	},
},

[gibfahn]

Markdown Code Blocks

Very simple one to surround text with markdown triple-backticks. Prompts you for the code language, or defaults to empty.

E.g. ysip~ then rust<Enter> would change:

println!("foo")

to:

```rust
println!("foo")
```

Implementation copied from #88 , adding here just because I looked for it here.

Mapped to ~ as it's Shift-` on my keyboard, and I've never needed to surround with tildes.

Implementation:

        -- Surround with markdown code block, triple backticks.
        -- <https://github.com/kylechui/nvim-surround/issues/88>
        ["~"] = {
          add = function()
            local config = require("nvim-surround.config")
            local result = config.get_input("Markdown code block language: ")
            return {
              { "```\n" .. result, '' },
              { "", "```" },
            }
          end,
        },

[thetic]

I get an error when I try this

ERROR E5108: Error executing lua ...are/nvim/lazy/nvim-surround/lua/nvim-surround/buffer.lua:233: 'replacement string' item contains neewlines
stacktraceback:
[C]: in function 'nvim_buf_set_text'
...are/nvim/lazy/nvim-surround/lua/nvim-surround/buffer.lua:233: in function 'insert_text'
...share/nvim/lazy/nvim-surround/lua/nvim-surround/init.lua:68: in function 'normal_surround'
...share/nvim/lazy/nvim-surround/lua/nvim-surround/init.lua:295: in function <...share/nvim/lazy/nvim-surround/lua/nvim-surround/init.lua:244>

[kylechui]

I believe that the \n is there in error.

[bendk]

Generics

Surround content with a generic type:

Before: String
Type: ysiwgBox
After: Box<String>

Implementation (basically copied from the function built-in)

                surrounds = {
                    -- "generic"
                    g = {
                        add = function()
                            local config = require("nvim-surround.config")
                            local result = config.get_input("Enter the generic name: ")
                            if result then
                                return { { result .. "<" }, { ">" } }
                            end
                        end,
                        find = function()
                            local config = require("nvim-surround.config")
                            return config.get_selection({ node = "generic_type" })
                        end,
                        delete = "^(.-<)().-(>)()$",
                        change = {
                            target = "^(.-<)().-(>)()$",
                            replacement = function()
                                local config = require("nvim-surround.config")
                                local result = config.get_input("Enter the generic name: ")
                                if result then
                                    return { { result .. "<" }, { ">" } }
                                end
                            end,
                        }
                    },
                },

[Quiroptero]

Spanish characters

Spanish language makes use of opening and closing punctuation characters, e.g: ¡Hola, mundo!. This little config is to get such Spanish-specific characters: quotation marks («,»), question marks (¿,?) and exclamation marks (¡,!).

Quotation marks

% Before
Foo

% After command: ysiws
«Foo»

Exclamation marks

% Before
Foo

% After command: ysiwe
¡Foo!

Question marks

% Before
Foo

% After command: ysiwq
¿Foo?

Implementation

surrounds = {
  ["s"] = {
    add = function()
      return {
        { "«" },
        { "»" },
      }
    end,
  },
  ["e"] = {
    add = function()
      return {
        { "¡" },
        { "!" },
      }
    end,
  },
  ["q"] = {
    add = function()
      return {
        { "¿" },
        { "?" },
      }
    end,
  }
}