Vim Plugins, surround.vim

Hi all. I am starting a new article series called “Vim Plugins You Should Know About“. This series of articles is going to be about Vim plugins that you should know about and perhaps even be using. The first article in this series will be about one of my favorite plugins called “surround.vim“.

If you are intrigued by this article series, I suggest that you subscribe to my posts!

Don’t worry, I’ll finish all the previous article series that I have started (creating and marketing a video downloading tool, famous awk one-liners explained, sed one-liners explained and mit algorithms). I just wanted to utilize my excitement and get this article published ASAP.

Okay, so what is surround.vim plugin? Here is what Tim Pope, the author of this plugin, says:

Surround.vim is all about “surroundings”: parentheses, brackets, quotes, XML tags, and more. The plugin provides mappings to easily delete, change and add such surroundings in pairs.

That’s what the plugin does. It allows you to easily delete, change and add various “surroundings” in pairs. For example, you may quickly wrap a line in an html tag, or you may delete a pair of { }, or you may add quotes around words, etc.

Let’s take a look at a few examples for each surrounding command: delete surrounding, change surrounding, and add surrounding. In the examples | indicates the position of the cursor.

Examples of deleting surroundings:

Surroundings can be deleted with the “ds” command. After you type “ds“, the command expects the surrounding target you want to delete. It may be any of three quote marks, ', ", and `, the eight punctuation marks, (, ), {, }, [, ], <, > , and a special ‘t’ target for deleting the innermost HTML tag.

Text              Command    New Text
---------------   -------    -----------
'Hello W|orld'    ds'        Hello World
(12|3+4*56)/2     ds(        123+4*56/2
<div>fo|o</div>   dst        foo

(| is the position of cursor in these examples)

See how easy it was to delete surroundings? Just 3 keystrokes. Compare it with doing it old fashioned way:

Text              Command    New Text
---------------   -------    -----------
'Hello W|orld'    F'x,x      Hello World
(12|3+4*56)/2     Bxf)x      123+4*56/2
<div>fo|o</div>   Bdf>wdf>   foo

(| is the position of cursor in these examples)

That was really messy, wasn’t it? I hope you start to see now how handy surround.vim is!

Examples of changing surroundings:

Surroundings can be changed with the “cs” command. The “cs” command, just like “ds” command takes a surrounding target, and it also takes the surrounding replacement. There are a few more surrounding targets for this command. They are w for word, W for word + skip punctuation, s for sentence, and p for paragraph.

Text              Command    New Text
---------------   -------    -----------
"Hello |world!"   cs"'       'Hello world!'
"Hello |world!"   cs"<q>     <q>Hello world!</q>
(123+4|56)/2      cs)]       [123+456]/2
(123+4|56)/2      cs)[       [ 123+456 ]/2
<div>foo|</div>   cst<p>     <p>foo</p>
fo|o!             csw'       'foo'!
fo|o!             csW'       'foo!'

(| is the position of cursor in these examples)

Examples of adding surroundings:

Surroundings can be added with the same “cs” command, which takes a surrounding target, or with the “ys” command that takes a valid vim motion. There is a special “yss” command that applies a surrounding to the whole line, and “ySS” that applies the surrounding to the whole line, places the text on a new line and indents it.

Text              Command      New Text
---------------   -------      -----------
Hello w|orld!     ysiw)        Hello (world)!
Hello w|orld!     csw)         Hello (world)!
fo|o              ysiwt<html>  <html>foo</html>
foo quu|x baz     yss"         "foo quux baz"
foo quu|x baz     ySS"         "
                                   foo quux baz
                               "

(| is the position of cursor in these examples)

You can also add surroundings while in insert mode. That is supported via <CTRL-s> mapping.

Please be very careful with CTRL-s. On many terminals it stops the output and your session will appear to be frozen! If that happens, use CTRL-q to unfreeze it. You may want to remove CTRL+s mapping from your terminal altogether. Add “stty stop ''” to your shell startup file (.bashrc for bash, .kshrc for ksh, etc).

For example (while in insert mode):

Command                  New Text
-------                  ------------
<CTRL-s>"                ""
<CTRL-s><CTRL-s><html>   <html>
                             |
                         </html>

(| is the position of cursor in these examples)

I urge you to try these mappings out. You won’t become a hockey player by just looking at the game, you have to play it yourself!

For a complete reference, here are all the commands/mappings surround.vim provides:

Normal mode
-----------
ds  - delete a surrounding
cs  - change a surrounding
ys  - add a surrounding
yS  - add a surrounding and place the surrounded text on a new line + indent it
yss - add a surrounding to the whole line
ySs - add a surrounding to the whole line, place it on a new line + indent it
ySS - same as ySs

Visual mode
-----------
s   - in visual mode, add a surrounding
S   - in visual mode, add a surrounding but place text on new line + indent it

Insert mode
-----------
<CTRL-s> - in insert mode, add a surrounding
<CTRL-s><CTRL-s> - in insert mode, add a new line + surrounding + indent
<CTRL-g>s - same as <CTRL-s>
<CTRL-g>S - same as <CTRL-s><CTRL-s>

How to install surround.vim?

  • 1. Download surround.zip. It will actually be a zip file containing the surround.vim script and documentation.
  • 2. Extract surround.zip to ~/.vim (on Unix/Linux), or ~\vimfiles (Windows).
  • 3. Restart Vim (or just source surround.vim script with “:so ~/.vim/plugin/surround.vim” on Unix or “:so ~/vimfiles/plugin/surround.vim” on Windows).
  • 4. Regenerate helptags with “:helptags ~/.vim/doc” on Unix or “:helptags ~/vimfiles/doc” on Windoze.

Type “:help surround” to read help.

Comments appreciated!

What plugins do you use? Your comments will help me and my blog readers to find more plugins which we might have not heard about. You may also share any tips and aha-moments that you have had while using vim. I might add my own and turn them into a valuable article. Thanks!