Hi all. I am starting a new article series called Vim Plugins You Should Know About. As the title suggests, this series is going to be about Vim plugins that you should know about and be using. The first article in this series will be about one of my favorite plugins called surround.vim.
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<strong>|</strong>orld' ds' Hello World (12<strong>|</strong>3+4*56)/2 ds( 123+4*56/2 <div>fo<strong>|</strong>o</div> dst foo (<strong>|</strong> 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<strong>|</strong>orld' F'x,x Hello World (12<strong>|</strong>3+4*56)/2 Bxf)x 123+4*56/2 <div>fo<strong>|</strong>o</div> Bdf>wdf> foo (<strong>|</strong> 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 <strong>|</strong>world!" cs"' 'Hello world!' "Hello <strong>|</strong>world!" cs"<q> <q>Hello world!</q> (123+4<strong>|</strong>56)/2 cs)] [123+456]/2 (123+4<strong>|</strong>56)/2 cs)[ [ 123+456 ]/2 <div>foo<strong>|</strong></div> cst<p> <p>foo</p> fo<strong>|</strong>o! csw' 'foo'! fo<strong>|</strong>o! csW' 'foo!' (<strong>|</strong> 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<strong>|</strong>orld! ysiw) Hello (world)!
Hello w<strong>|</strong>orld! csw) Hello (world)!
fo<strong>|</strong>o ysiwt<html> <html>foo</html>
foo quu<strong>|</strong>x baz yss" "foo quux baz"
foo quu<strong>|</strong>x baz ySS" "
foo quux baz
"
(<strong>|</strong> 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>
<strong>|</strong>
</html>
(<strong>|</strong> 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.
See you next time!