Transcending the Mundane with Vimscript

This chapter will cover Vimscript in all its glory. We will go into quite a bit of detail, but since we only have so many pages the coverage will be somewhat spotty. Hopefully, this chapter will get you interested in Vimscript enough to start your own research, and maybe you can use it as a reference as you build your early plugins and scripts. In this chapter, we will look at the following:

• The basic syntax, from declaring variables to using lambda expressions
• Style guides, and how to keep sane when developing in Vimscript
• A sample plugin from start to finish—from the first line to publishing it online

Technical requirements

This chapter walks you through learning Vimscript by using numerous examples. All the examples are available on GitHub: https://github.com/PacktPublishing/Mastering-Vim/tree/master/Chapter08. You can create the scripts on your own as we're working through this chapter, or download the files from the repository to play around with.

Why Vimscript?

You've already encountered Vimscript when you worked on your .vimrc. What you may not have known is that Vimscript is actually a Turing-complete scripting language—there's no limit to what you can do. So far, you've used it to set variables and perform a few comparison operations, but it can do so much more!

You will learn how Vimscript not only helps you understand Vim configuration better, but lets you solve text editing problems you encounter by writing functions and plugins.

It's pretty awesome.

How to execute Vimscript

Vimscript is made up of commands you run in command-line mode, and really is just a sequence of Vim commands in a file. You can always execute Vimscript by running each command in command mode (the one you prefix with :), or by executing the file with commands using a :source command. Historically, Vim scripts have a .vim extension.

As you're following along with this section, you may want to create *.vim files to experiment in. You can execute the files by running this:

:source <filename>

A much shorter version of that is this:

:so %

Here, :so is a short version of :source, and % refers to the currently open file.

For example, I just created a variables.vim file to play around with Vim's variables. I could execute its contents with :so %:

Alternatively, I could run each command in command mode. For example, if I wanted to print the contents...

Learning the syntax

Let's take a lightning-fast deep dive into Vimscript's syntax.

This section assumes you're comfortable with at least one programming language, conditional statements and loops in particular. If that's not the case, you will most certainly be better off finding a more extensive tutorial. Vimscript deserves its own book, and Steve Losh wrote just that: Learn Vimscript the Hard Way is easily the best Vimscript tutorial available (and it's free on the web!).

Setting variables

You've already discovered some basics of Vimscript syntax. To set internal Vim options, you use the set keyword:

set background=dark

To assign a value to a non-internal variable, use the let keyword:

let animal_name...

A word about style guides

Consistent style is important. One of the more prominent style guides for Vim is the one published by Google: https://google.github.io/styleguide/vimscriptguide.xml. It highlights some common development practices and outlines common pitfalls.

Here are some excerpts from the Google Vimscript style guide:

• Use two spaces for indents
• Do not use tabs
• Use spaces around operators
• Restrict lines to 80 columns wide
• Indent continued lines by four spaces
• Use plugin-names-like-this
• Use FunctionNamesLikeThis
• Use CommandNamesLikeThis
• Use augroup_names_like_this
• Use variable_names_like_this
• Always prefix variables with their scope
• When in doubt, apply Python style guide rules

Give the Google Vimscript style guide a read, it's rather useful even if you never plan on doing more than customizing your .vimrc. It'll help with self-consistency.

...

Let's build a plugin

Let's try building a simple plugin; this way, we can learn by the example.

A common task you have to perform when working with code is commenting out chunks of code. Let's build a plugin that does just that. Let's (uninspiringly) name our plugin vim-commenter.

Plugin layout

Since the Vim 8 release, there's thankfully only one way of structuring your plugins (which is also compatible with major plugin managers, such as vim-plug, Vundle, or Pathogen). The plugins are expected to have the following directory structure:

• autoload/ lets you lazy load bits of your plugin (more on that later)
• colors/ color schemes
• compiler/ (language-specific) compiler-related functionality
• doc/ documentation...

Further reading

Vimscript is a long and complex topic, and this chapter only brushes it. If you want to learn more, there are a few options.

You can read :help eval, which contains most of the information about Vimscript.

You can also choose to follow a tutorial online, or pick up a book. A lot of people recommend 'Learn Vimscript the Hard Way' by Steve Losh, and it is indeed rather good. It's available online at http://learnvimscriptthehardway.stevelosh.com/ (you can buy a paper copy from the website as well).

Summary

That was quite a bit of work! Let's do a quick recap!

We've learned that Vimscript lets us take Vim anywhere we want, limiting your productivity only by your imagination. We've covered setting and manipulating variables, working with lists and dictionaries, surfacing output, and control flows using if, for, and while statements. We've also covered functions, lambda expressions, the Vimscript equivalent of classes, as well as some more functional approaches using map and filter functions. We've also looked at Vim-specific commands and functions.

We've also built our first plugin, vim-commenter. The plugin lets you comment and uncomment lines in a Python file at the press of a button (well, two). We've learned how to structure our plugins, and how to use Vimscript to accomplish our goals. We've even brushed distributing the plugin...