Vim Recipes ‣ Typing ‣ Inserting Snippets

Inserting Snippets

Problem

You repeatedly type the same constructs, so want to expedite the process by typing a few letters then have Vim produce the boilerplate text.

For example, to enter a HTML <table> you want to type table<Tab> then have Vim produce:

<table border=" ">
    <tr><th> </th></tr>
    <tr><h> </th></tr>
  </table>

Solution

Use Michael Sanders' snipMate plugin, which provides a subset of the snippets feature of the Textmate. editor.

Follow the installation instructions on the script page, then open a HTML document with Vim, e.g. vim test.html. Type table<Tab>. The <table> given above should be inserted into your document.

In the above example, table is the trigger, the text you type, and the resultant HTML is the snippet, the text that is inserted after typing trigger<Tab>.

snipMate is distributed with a collection of snippets for common file types. To see a list of snippets available for the current buffer execute <Ctrl>-R <Tab>. To write your own see :help snipMate.

Several snipMate users have made their snippets available on GitHub.com:

Discussion

The power of snipMate comes from how it lets you navigate the snippet once inserted. Consider again the <table> example:

<table border="1">
    <tr><th>2</th></tr>
    <tr><h>3</th></tr>
  </table>4

The numbers, e.g. 1, in the above output represent tab stops: the positions where the nth <Tab> after the trigger will move the cursor to. So, the user types table<Tab> to insert the snippet. His cursor is placed in position 1 so he can enter the border size. He then hits <Tab> again to position his cursor in 2 so he can enter the name of the header for the first row. And so on.

Some constructs require user-entered text to appear multiple times. For instance, HTML authors may want to enter an <option> element like the following:

<option value="placeholder">placeholder</option>

In this example, placeholder is placeholder text that needs to be entered twice. snipMate lets you enter the text in value="placeholder">, and have it copied into >placeholder< as you type.

To learn more about snipMate and its features see :help snipMate.

There is also a similar snippet engine called XPTemplate.

Comparison of Techniques to Auto-Complete Text

We have discussed various approaches to automatically inserting text in this chapter, so let us recapThe forthcoming is intentionally opinionated and simplified because a detailed analysis of every possibility is beyond the scope of this book. That said, if there are any factual errors, please let me know..

Templates can be used to associate a skeleton document with a file extension, whereby opening a file whose name ends with that extension causes the skeleton document to be inserted into the buffer. The advantage of this approach is that it doesn't require the installation of any plugins, but other than that snipMate can be used to achieve the same effect. For example, SnipMate has a trigger named docx which inserts the XHTML 1.1 doctype:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

This can trivially be adapted to insert whatever boilerplate HTML you desire.

Abbreviations can be used to replace a piece of text with another piece of text after pressing <Tab>. They differ from snippets in two key respects. Abbreviations are typically defined globally, whereas snippets are defined for specific filetypes. For instance, a trigger of for could insert a C for loop when editing C source code, or a Ruby for loop when editing Ruby code. More importantly, snippets have the notion of placeholders that can be tabbed between. In general, snippets can do everything abbreviations can, and more.

Insert-mode auto-completion can auto-complete text based on what has already been typed or the grammar of the current file type. For instance, you can auto-complete a variable name that you have declared previously, or a language keyword. This form of auto-completion augments snipMate: use the former to complete unique definitions and names in the current file, and those that it includes; use the latter to complete pre-defined snippets. Where the two's functionalities overlap, snipMate has a simpler interface (type a trigger, hit <Tab>), and is, arguably, easier to configure.