Check out my new project: Peer to Peer - watch how experts solve tech problems.

Learn more

Check out my new project: Peer to Peer - watch how experts solve tech problems.

Vimprint - a Vim keystroke parser

I sometimes get asked what software I use to reveal the Vim keystrokes in my video tutorials here on The fact is that I add them by hand in post-production. It’s not fun!

When I run my Core Vim Masterclasses I use Keycastr to show what I’m doing in realtime. Keycastr uses Growl-style notifications to show all keystrokes across all applications, including every letter I type while communicating in a chat room, for example. It’s not ideal, but it’s better than nothing! I would love to have a dedicated program for visualizing my keystrokes in Vim, so I’ve started building Vimprint to scratch that itch.

My wishlist for Vimprint

My goal is to make Vimprint show all Vim keystrokes in realtime, so that I can use it when teaching Vim. In addition to showing which keystrokes were pressed, I’d like Vimprint to be able to give a bit of extra context: what does each command do, and from which mode was it triggered? Ultimately, I’d like Vimprint to handle all of Vim’s built-in functionality, and for it to be extensible so that it can be made to understand commands supplied by popular plugins such as surround.vim.

I gave a presentation on Vimprint at this month’s VimLondon meetup. You can watch the video on Vimeo and refer to the slides on speakerdeck.

Similar projects

In researching this topic, I’ve come across a few similar projects that have influenced or inspired me. (Let me know if I missed any.) VimSpeak by AshleyF turns spoken English into keystrokes. Check out this demo, where the author completes a VimGolf challenge by talking to his computer. It’s awesome!

Turning English into keystrokes is the opposite of what I want to do. I want to turn keystrokes into plain English descriptions, and Vimsplain by pafcu is a project that does exactly that. Vimsplain is run as a batch job at the command-line. That’s cool! But I want to get these kinds of explanations in realtime.

George Brocklehurst from thoughtbot has achieved that with Vimulator, which is a Vim Simulator (as the name suggests) that runs inside the browser. I love the way that Vimulator renders and explains keystrokes, but the task of implementing Vim in JavaScript I find daunting.

The VimGolf client tracks your keystrokes, and sends them to It does this by launching Vim with the -w {scriptout} option, which logs all keystrokes to the specified {scriptout} file.

That seems like a good starting point, but there’s a problem with the -w {scriptout} option: it only writes keystrokes to the specified file when Vim exits. To create a realtime visualization, I would need a realtime stream of keystrokes.

Kana Natsuno (one of my Vim heroes) came up with this single-line patch, which disables buffering of the -w option. With a custom build of Vim using my live-stream-keystrokes branch of MacVim, I can get the realtime stream of keystrokes that I need. Sweet! Now I just need to parse it.

Parsing Vim keystrokes with Ragel

Ragel is a state machine compiler, which seems like a good fit for this problem. After all, Vim itself is a finite state machine of sorts.

As a demonstration, I’ve created a simple.rl ragel program that parses a tiny subset of Vim’s commands. Install ragel (brew install ragel on a mac), then you can compile and run this program:

ragel -R simple.rl
ruby simple.rb

As well as compiling executable Ruby code, Ragel can generate .dot graphs, which can be viewed using Graphviz. Here’s the state chart visualization of the simple.rl program (created with the command ragel -Vp simple.rl):

simple Vim state machine

I’ve found this kind of visualization to be very helpful in debugging Ragel programs.

Contributions welcome

This is an ambitious project. I’d welcome any help on it that I can get. If you’d like to #pairwithme on Vimprint, then please get in touch.

I’ll be presenting a session on Modelling State Machines with Ragel at Eurucamp this year. I’d love to be able to demonstrate Vimprint in action by that date.


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with Thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from Thoughtbot..