Futurile

• Work
• Play
• Resources
• About
• Archive
• Search

Vim surround plugin tutorial

Anyone who uses Vim extensively knows a lot of it's power is being able to manipulate text as a set of components. We do this using text objects and motions. There are a lot of useful vim plugins that extend these capabilities.

Tim Pope's vim surround plugin is one of the most popular [1] plugins. It provides text objects to deal with pairs of things surrounding something else.

This tutorial covers how to install the plugin, how to use the major capabilities and provides a set examples for each of the operations. For a visual overview I've created a video (3:15 mins) linked on the left. It demonstrates a few of the capabilities that this post covers while marking up a text document with HTML, including visual selection and the repeat operator.

The first thing any plugin has to answer, is whether it's truly useful. Surround.vim comes into play when you want to alter brackets, a common requirement in development. It's also useful when marking up a document to HTML since it lets you surround text with mark-up very quickly. Vim's built in capabilities for handling brackets as text objects are useful, but here's two situations where the additional capabilities of this plugin help:

# A python list
# di] removes the 'i'nner, or da] removes the whole thing
# but we want to remove the square brackets only
['one', 'two']

# We want to put some quote marks around the text
# We could do i, move 3 words and i again - not very efficient!
print(Hit the button)

Installing surround.vim

To install it use the plugin manager of your choice and add to your .vimrc. I'm using NeoBundle:

NeoBundleLazy 'tpope/vim-surround', {'autoload': {'filetypes': ['clojure','rst','python']} }
NeoBundleLazy 'tpope/vim-repeat', {'autoload': {'filetypes': ['clojure', 'rst', 'python']} }

The first line makes vim-surround available and loads it if we're editing a Clojure, reStructuredText or Python file. The second line does the same thing for the vim-repeat plugin which we'll cover later. The reason for using NeoBundleLazy is that with lazy loading Vim still starts up quickly, but can load these plugins when required. After a restart and load, we can check it's available with :NeoBundleList within Vim.

When the plugin is loaded a new text object for surround is available, it's called with s. We use it with the normal mode commands specifying a surrounding text object to act on. Taking our examples from above:

# remove the brackets
# ds[ -  'd'elete 's'urrounding [
['one', 'two']

# add quote marks
# ys3w" - Add (y) 's'urrounding 3 words with "
print("Hit the button")

A bit more formally the structure is:

<command><surround object>[count]<surround target>[replacement]

Where <command> is one of the standard Vim ones such as delete (d), change (c) or visual (v). It also adds a new one add (y) for where you want to add something around the object you're operating on. The <surround object> is called with 's' which tells Vim we're trying to operate on something surrounding some text. The next parameter is the <surround target>, such as a bracket or a quote mark. The last parameter is the <replacement> which is required when you're changing (with c) or adding (with y) something. As with other Vim commands it's possible to use a [count] when specifying the surrounding object to operate on, e.g. above we acted on three words.

The easiest form is the delete command so lets look at that first.

Delete surroundings

To delete we use ds, the next character determines the target to delete. Some examples:

"Hello world!"
  [] <--- cursor

ds"

Hello world!
[] <--- cursor now

<p>Start here</p>
       [] <--- cursor

dst

Start here
[] <--- cursor now

(var1, var2)

ds(

var1, var2

The cursor can be anywhere within the surrounding text object we're operating on, when the command is complete the cursor moves to the start of the object we operated on. Also, unlike other text objects there's no i or a option for changing how it selects the area.

Change surrounding

To change a surrounding we use cs, this deletes the supplied text-object and replaces it with the second argument. When used in this way the cursor does not enter Insert mode at the end of the command. There are two ways to use it:

• Change one surround to another: cs<surround target><replacement>
• Change one surround to another, putting the new ones on separate new lines: cS<surround target><replacement>

Examples of how to use it are:

"My kingdom for a horse"
      [] <--- cursor here

cs"'

'My kingdom for a horse'
[] <--- cursor here now

'Look, to the East'

cS'<p>

<p>
Look, to the East
</p>

Add surrounding

Often, rather than altering some existing mark-up or brackets, we want to add some additional surroundings. Add a surrounding uses ys, the following item is the additional mark-up, brackets or text that will placed either side. The ways it can be used are:

• Wrap the vim motion or text object in the second argument: ys<motion|text-object><addition>
• Change the current line and wrap it with the second argument: yss<addition>
• Change the specified motion, putting the new addition on new lines and indenting the text: yS<motion><addition>
• Whole line and do the above: ySS<addition>

Some examples of using these methods:

he said, Boo! scary huh
         [] <--- cursor

ys$"

he said, "Boo! scary huh"

print var1, var2
      [] <--- cursor

ys3w)

print (var1, var2)
      [] <--- cursor

34, 21, 7
  [] <-- cursor

yssB

{ 34, 21, 7 }
[] <-- cursor moves

Jack said, "Done it!"
           [] <--- cursor

ySf"t

Jack said, <blockquote>
    "Done it!"
</blockquote>

defn -proc1
    [] <--- cursor

ySSb

(
     defn -proc1
)

Visual surround

In visual mode, the surround object is called with S, and then an argument that wraps the visual selection. The keyboard usage is something like this:

v                         # Enter visual mode
<visually select>         # Use the keyboard to select the section of text
S                         # Press upper case S
"                         # Specify what you want to surround the visual selection with

• In linewise visual mode the surrounding are placed on separate lines and indented: vS<surround target>
• In block wise visual mode (Ctrl-v) each line is surrounded: vS<surround target>

Add two eggs
   [] <--- cursor

viwS*

Add *two* eggs
[] <--- cursor now

Consider this, when
we create an object
we take more memory.

Shift-v,
<highlight the text>
S<p>

<p>
Consider this, when
we create an object
we take more memory.
</p>

6 eggs
4 apples
2 pints of milk

Ctrl-v
<highlight the text>
S<li>

<li>6 eggs</li>
<li>4 apples</li>
<li>2 pints of milk</li>

Surround targets

A surround target is something where the plugin recognises that it can operate on it. With the ds and cs commands the parameter is a surround target to operate on. As we've seen the targets are often the first letter of a standard vim motion or text-object. The most common ones are:

Customising vim surround

Many of the examples for vim-surround are marking up HTML - the plugin is aware of HTML and XML tags. We can imagine other situations where it would be valuable for the plugin to recognise how to add a tag around some text: for example being able to mark-up a Sphinx or LaTeX document with defined tag shortcuts.

As an example, the simplest case is adding a short-cut for a reStructuredText file where we want to add bold (which is two **'s around some text). We'll assign it to the o key, because b is is a vim default text-object for brackets and we don't want to over-ride that. We're only going to have this mapping for reST files, so we open a rST file and check the filetype with :set filetype? which confirms it is rst. Also in vim, we can check the hex for the o character with :echo char2nr('o') which returns 111. Then in our .vimrc we do:

" put ** around the text, when used with ysso, or v<highlight>So
" These two lines do the same thing
autocmd Filetype rst let b:surround_111 = "**\r**"
autocmd FileType rst let b:surround_{char2nr('o')} = "**\r**"

Now, when a reStructuredText file is opened and we do something like ysso it will place rst bold mark-up around the line.

The constraint in vim-surround is that we can't use complex calls like "<leader>b" to call a surrounding, we can only define single letter shortcuts. Complex shortcuts may be possible with the vim-sandwich plugin, but I'm not totally clear on it. If this idea is attractive, there's a utility plugin called vim-surround_custom_mapping, and an answer on Stackoverflow which is worth looking at.

Repeat plugin

The repeat plugin extends Vims repeat command (.) so that it works with plugins - in this case enabling vim surround to work with the repeat command. It lets us repeat ds, cs and ys. The one wrinkle is if you do a visual selection then it will repeat the size of the visual selection.

'Bob', 22, 'Paris'
'Sarah', 34, 'New York'
'Karen', 54, 'London'

yss)
.
.

('Bob', 22, 'Paris')
('Sarah', 34, 'New York')
('Karen', 54, 'London')

Parting thoughts

I find the surround plugin adds a nice boost to editing code, I just need to get the muscle memory really embedded. If you've used the plugin, or have any thoughts on how to use it, please leave a comment!