Follow me on Twitter for my latest adventures!
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!
Facebook
Plurk
more
GitHub
LinkedIn
FriendFeed
Google Plus
Amazon wish list
Comments
What does this plugin do that text objects doesn't provide already?
JB, this plugin uses text objects to apply surroundings.
Comment copied from HN:
I tried this plugin a few days ago, but it seemed to break the s (substitute) command, so I removed it. Does someone know how to make it work?
The problem is the following: Write a line of text, select part of it using v, then press s to remove the selection and enter insert mode start replacing it. This doesn't work anymore when surround.vim is loaded. Too bad, it sure looks great…
thamer, replied to you on HN. Copied here:
Try 'R' instead of 's' that you were used to.
OR
Edit surround.vim and comment out the 's' mappings in visual mode.
Instead of 's' for substitute, try 'c' for change.
Peteris, I seem to be hitting this bug: http://cygwin.com/ml/cygwin/2003-09/msg01125.html when I hit Ctrl+S in my VIM. Then I had to hit Ctrl+Q to unfreeze.
I'm on a Solaris machine running dtterm and ksh. Any idea on how to get around this problem?
Srikanth, that is not a bug at all. It's your terminal controlling the flow. With Ctrl+S you stop the terminal, with Ctrl+Q you restart the output.
To avoid this "bug", try redefining the Ctrl+S at terminal level:
And put it in your .profile or .kshrc file.
Surround is one of the plugins featured as one of the 15 best vim plugins here..
15 Best Vim Plugins
Check out the other 14 to have a highly customized efficient vim environment.
surround.vim looks very useful. I've wanted something similar in the past but I was too lazy to search for it. Thanks for the tip!
Vim by itself is usually enough for me, so I haven't tried many plugins. The only plugin that I use regularly is vim-latex; it's amazing how fast one can type LaTeX documents with it (more efficient than using a wysiwyg, me thinks).
Thanks for blogging about this plugin, I absolutely dig surround.vim!
FuzzyFinder.vim and taglist.vim are two other staples I would definitely add to the list.
Tim
Apart from surround.vim, my favourite editing script is yankring.vim. Works really well, with lots of delightful features.
I also use bufexplorer.vim winfileexplorer.vim taglist.vim and winmanager.vim to get all that ide functionality.
Another nifty plugin is the ZoomWin.vim plugin, which allows you to maximise a vim window, and then restore your previous window configuration. I have tons of plugins lying around, many of which I can't remember what they do.
Oh yeah, the themes.vim with all the colourschemes is necessary as well.
Wow nice plugin! Already using it :)
I can do that surround removal shit in under a second with clever use of cmd+cursors/option+cursors shift and delete when I'm in textmate.
and I can do it instantly without having to remember that obscure command to perform something this abstract.
You think your saving time because your calling automation, but really the amount of time you'll be wasting in remembering that wont be saved at all.
If we both did it at exactly the same time I would be finished before you even started typing.
Shortcuts are mostly a myth, you feel more productive when your actually slower.
dogmachine:
You mock vim users for using shortcuts to delete text, whilst giving the example of . . . yourself using shortcuts to delete text. *laughs*
How is remembering a "clever use of cmd+cursors/option+cursors shift and delete" any easier than remembering 'ds'?
Unfortunately, commands added by this plugin are not repeated by the '.' command -- they are treated as a couple of separate commands. For example, if you have two words and you move the cursor to one and do ds", then you move the cursor to the other and hit '.' and it won't preform ds", it will just delete the word under the cursor. Kind of a drag -- anybody know how to change this?
As usual, people hide behind pseudonyms to spew their craziness on the net. I guess you know you look a bit silly to any prospective employer who may read your response.
When im adding surroundings, i usually select the target text in visual mode then hit s) or s" etc. This requires less thinking than using text objects which often makes it faster.
Legend: if you use repeat.vim (by the same author) then some of the commands are repeatable with "." but not all :(
Legend: install repeat.vim
http://www.vim.org/scripts/script.php?script_id=2136
Thanks Peteris, of course it's not a bug; it's a feature. What was I thinking! :)
Nice plugin. Autoclose is also very useful.
A few comments:
- Use <CTRL-g>S if you want to keep <CTRL-s> for your terminal.
- Debian makes it easy to install vim addons: apt-get install vim-{scripts,addon-manager} && vim-addons install surround
Cheers.
You can also have a look at the project plugin which let you load all files of a project, grep some pattern in the files, run a script on all files of the project, etc.
You can find a small introduction here.
come out, we've got the place surrounded!
I have been using VIM for a long time, but I have not heard about this plug-in. Thank you!
I noticed that in visual mode s is redundant because c does the same thing. So having s rebound in visual mode is not a problem for me.
It's a pretty sweet plugin IMO.
Acutaly, I don't find this very helpful. There are still to many commands, and even with repeat.vim, the repeat action doesn't always work.
I'll try it out a little more, but not going to hold my breadth.
If you're looking for Vim plugins that people should know about... You might want to check out Txtfmt (The Vim Highlighter), which provides a sort of "rich text" highlighting capability in Vim: fg/bg colors and all combinations of bold, underline, italic, etc...
Vim download page:
http://www.vim.org/scripts/script.php?script_id=2208
Screenshots:
http://www.freewebs.com/txtfmt
Disclaimer: Yes, I am the author, but my experience has convinced me that there are still a number of people looking for this capability in Vim, who aren't aware that this plugin exists.
I noticed that in visual mode s is redundant because c does the same thing. So having s rebound in visual mode is not a problem for me.
so i think it is sweet plugin
How to keep s unmapped in Visual mode:
This is directly taken from surround.vim's help file, thus the author pretty much is aware about the issue.
Very usefull plugin, I suggest the pathogen plugin and this article [1] contains interesting things. Finally this fantastic screencast [2]
1 - http://stevelosh.com/blog/2010/09/coming-home-to-vim/
2 - http://vimeo.com/15443936
This is no question specifically regarding the add on, but googling didnt quite help me: I'm new to Ubuntu and I can't seem to find an installation directory of GVim where I could eventually put the plugins. In usr/bin I see a couple of related files, but no folder to extract into? Or should I directly put it in usr/bin?
Thanks in advance
Hi hmmm. Put it in your home directory in
.vim/pluginsdirectory!This should actually be ~/.vim/plugin (and not plugins)
Dear peteris ,
pls could you tell me how to use vim plugins for source code trace like for example i want to know which function where it is defined similarly class, stracture. if not understood see the link you will get ideahttp://www.thegeekstuff.com/2009/04/ctags-taglist-vi-vim-editor-as-sourece-code-browser/
This Helped. Thanks !
run stty -ixon on terminal.
check out the "i" (in) operator. That's stock in vim, which is nice so you don't have to worry about installing extra plugins.
"Hello W|orld" di", ci" etc work just as this does.
You can certainly do it in " ' ( [ {. If you get a good xml plugin then I will work in >< as well.
The shortcuts have changes a little bit:
S - in visual mode, add a surrounding
gS - in visual mode, add a surrounding but place text on new line + indent it
Leave a new comment