Your First Vim Plugin

hello again everyone once again my name is Chris to me I want to thank everyone for coming out I especially want to thank Mike for giving that first talk was excellent so a big round of applause one more time for Mike so I think Mike's talk was a great introduction how to get started and then why you're gonna fall in love with them and I think you did a great job highlighting a lot of things that make them special make them interesting so now I'm going to go kind of the other end of the spectrum hopefully this will be an accessible talk for everyone but it might be a little bit advanced don't worry if that's the case the idea here is to get you inspired get you interested get you moving towards your first bin bug in so the first thing that you want to share is I've actually put together a git repo to support all of this I posted that up to my Twitter Chris to me CHR is T oo m ey I'm Chris to me on Twitter and Chris to me on github and this has all of the notes and the sample code that I'm going to be running through as we build up a few of these plugins so you can bookmark that come back to it I'll also be flushing that out probably over the next day or so but at a minimum this much will be up there so one of the things that I think's really important to highlight about plugins is when you think about them there's I use them every day I've learned change in our parens I've learned delete a word and you get comfortable with all of that but plugins always seem like this thing that only T Pope writes and that's it there's a small class of people in the world that can write vim plug-ins and the rest of us are destined to just use them and we're stuck with what we get okay he's amazingly good at it and he just writes so many I don't think I've ever given a talk here without mentioning T Pope at least three times that's the nature of them but what I'm here to tell you tonight is that vim plugins are within basically anyone who has gotten even a little bit comfortable with them you can write a vim plugin so we're going to start from the simplest of vim plugins and we're going to build it up successively add a few ideas and show you how you can actually start into this yourself and take what is the best text editor in the world and make it even and even more perfect for you so let's get started I have four examples that are clearly in the wrong order but markdown is going to take care of that for me so who cares the first one we're going to start with is fixing a spelling error so sounds really exciting I know I have two different documents here I'm actually gonna kill that on the Left we have a markdown document markdown is a plain text markup format that can be compiled into HTML the specifics of that are not that important but the important idea is that I'm writing prose here so the idea of a spelling error is a thing so I have carefully crafted a spelling error right there in the middle of the page and what I want to do is capture a bit of functionality so I'm going to jump over here what I'd like to do is I would like to fix that spelling error without leaving the spot that I'm on so I want to teach vim this new idea then has some of the ideas built in but not everything so I want to build this up so the first thing we're going to do is we're going to figure out what are the pieces I need in order to be able to fix the spelling error and particularly keep my cursor where it is so the first thing is I need to get to that spelling error and anyone who's particularly familiar with them will know that motions are a thing that then has many you can move by words you can move by finding a certain character you can move by searches but them has actually even some weirder ones in there so in this case I'm going to use left bracket s and that will jump me back to the previous misspelled word so this is a built in feature of them this is not something that I added but this happens to be there and we can build on top of that so now I found my way back to that word the next thing I want to do is I want to fix it so vim does have built-in spell checking and the ability to hook into a dictionary file and offer suggestions so in this case I'm going to bring up the menu which is done with Z equals and now then kind of takes over the whole screen offers me this whole list so spelling spilling spellings it offers me a few different things similar to Microsoft Word but way better and I can hit a number to select any of these but I don't actually want to interact with this menu I want this automatic I just wanted to fix the spelling error so instead of doing that I'm going to use another feature them which is the idea that commands or operators can take counts so instead of saying Z equal and I get this big menu I'm going to say one Z equal and that tells them take the first spelling suggestion and replace my word with it it's very similar to Google I'm feeling lucky just go with that first one so now I have most of the pieces that I need now all I need to do is is bring them together so if we go back over here starting from this point I can say then remember this spot and the way to do that is with M to mark and I say M again to tell it where I want it to mark so NN says mark this spot as M so now we remember where we are I can hit left s that'll jump me back one Z equal I now fix my spelling error and tick M ticking the back tick on the tilde character that will jump me forward again so talking that out obviously takes a few minutes but it turns out that you can just capture all of that and use a function of them this is a command that I'm running down here FF and see it's all try and spell this out for you this is the normal command particularly normal bang which says execute these exactly as I give them to you so from there it's mm1 Z equal was it take m I think that sounds about right yeah I got to do that I happen to be on the word though I can actually try that again nm left bracket s this is I can edit that and then I can run it again and there that time it actually did it exactly as I want so if I undo what's nice is you actually hop back to the word so if it doesn't pick the right suggestion this thing still works out great so now I've composed everything I need I have a motion to get to where I want to I have a single operator that will change the word and give me back the correct style or at least the first suggestion and move me back to that space all of which composed into a single action so now what I want to do is I want to capture that off for reuse so I'm going to type out what I want to do there's n-no remap so give me a normal mode Matt the no remap Stang is a fancy subtlety don't worry about it but this is a normal map it's using my leader key which in my case is the spacebar might be the backslash backslash that's a configurable thing but for me that means the space and then sp so if I type space SP in sequence it will do whatever I tell it so in this case I'm going to type out that same command that I just wrote see if I can still remember it mm 1 Z equal and then xB I've got to move back to it 1 z equal to M and to close this out I need to put in this special sequence here CR and brackets that means character turns same as hitting Enter so now I've captured all of this and now all I need to do is tell them use this so if I move down here I've actually brought in a special line this is some of my secret sauce this is source this current file so new command % will represent the current file so by typing space SOP I can source in this file so now I've done that space SOP I jump back over here I now have that functionality built in and I can say space SP and I've talked doing something new so to me this is pretty cool it even has that nice undo functionality where it brings me back to the word and this is basically a vim plugin it's not as clean it's not as well-dressed but this is custom bin functionality that you've built out and what's great about it is it builds on what you already not builds on the text objects and the motions and the commands that you use in vim everyday and that you're comfortable with and particularly this guy right here the normal bang allows you to just say execute these as if I was typing them in so you can save off sequences of edits and you have them be reusable so the one suggestion that I usually make with this to make this a little bit fancier is to wrap it in a function this is where you get really fancy so this will be fixed last spelling error and inside of there let's go grab this and I don't actually need everything from before I can just use this it's equivalent to having it with a character turn and now instead of leader s key executing that command it's going to call this function it's a little long for the given line but that's okay so this is not functionally different in fact let me source it and demonstrate that real quick but hop over here leader SP still works just the same capture that same functionality but to me this form is much better is the next time I come in here I don't have to try and remember what that random sequence of characters means I've given it a name I know what it is the next time I come around here so that's the basis that's the simple idea that got me started into vim plugins so before I go too much further there any questions and some of what I've shown I'm happy to talk about this again after as well-known to anything tell you one but if there are any high-level questions before we go on short that's at that time that's when you make it real pretty and fancy and actually my recommendation is you don't even need to know that yet the idea of a plug-in is it's this reusable bit of functionality but it's actually very easy to put this into your MRC and in my case this actually does live in my by marci let's go yeah if I wanted to do that so somewhere in my dem RC I actually have this pretty much the exact same code that I have up there is captured in my vim RC so the last thing that I'll do in this talk is will show how to extract that out and make that a usable thing that you can share with other people but wanted to start with this idea sequence of normal mode operations grab them save them off give them a name and give them a key map and now the world's a better place because vim knows a little bit more what you need and cool so I will move on now to the next example which is move items to the top of the list so we'll open this one up move that's the one so again same idea here the distinction that I'll make in this case remember what I'm trying to do we'll jump down the goal here is I have two different lists this is say my to-do file and within it I have a list of projects and two different lists what I want to be able to do is I want to move this line to the top of this list so I don't go all the way to the top of the file don't want to go to the top of this list but I want to go to the top of this list right here so again we can do the same thing we can go through the sequence how is it that I would do this if I were just editing the file and save that off but there's a little bit of extra magic that I can do this time before starting through that sequence I'm going to hit Q and then Q again and it says something magical with it and it starts recording this is recording a macro again a lot of people probably think it's scary not for them it's very simple all it does is capture the keystrokes exactly as you run them and saves them off for later use so now that I'm recording rather than having to type out the whole sequence again I can just figure out what it is that I need to do in this case I've tweaked with this a little bit so I know I need to move up mark that location move back down now I'm going to delete the line that I'm on because I want to take that one up so that's D D I'm going to use the left curly brace that is Vin's beginning of paragraph' motion so that moves me right up to this empty line I'm going to hit P that pastes in the line that I just deleted and then tick M to jump right back down to where I was now once I'm at the end of that I hit Q once more and that stops the recording so now I captured that whole sequence of text but I don't need to retype it or anything like that actually undo that motion I can come in here and I can say at Q and it reruns that I can say a Q again and we get the same thing and now I'll undo them another really nice feature of capturing these combined sequences of actions you'll notice I was able to undo that in one sequence them is now treating this as if it's one thing that I'm doing I've taught been that there higher-order concept of moving an item within a list it actually consists of a sequence of undoable events in them but now I said none of them this is special treated that light and so now again the idea is I want to save this off or we use later so I can do that with the same sort of functionality in this case we'll say so I want to do that I'll go straight forward I'll say M 1 M is a operator so it waits for a second key so that's a fine thing for me to do in the world at least I think it is and same thing normal bang but now here's the really fun part I've saved off those keystrokes and I can ask them for them back the way you can do that it's in a register so in insert mode control R and then Q will actually dump out the contents of that register so there is that sequence can move up and then mark Raman J back down D D to delete the line jump to the top pasted back but this time I didn't have to remember it and retype it off the top of my head would get really annoying you have to do it that much but again the same idea here I tack a CR at the end i source in this file using that same source command that i have down here and now i can say m 1 and that moves that to the top again the next step that i would do here is I would wrap that in a name function and I might even make this one a little bit configurable and I can show you what that looks like I have a readme that contains the full form of this code and I'll make that a little bit bigger this is the actual code that's in my bin RC that gives me this functionality it's a function that I titled move on and I actually used a loop I actually create an one and two and three within that I've just continually iterated over the week saying you know I would like a little bit smarter I wanted to move like this and this allows me to move to any position within a sequence of lines but this code started is exactly what I just showed you I recorded a macro I dumped it out of my Ben Marcy I wrapped a function around it to give it a name and then I didn't think about it for a few days until it annoyed me so again this is this is the sequence that gets me to my plugins which at this point I've written couple of more than I would have expected as I started to click the list for this so again we'll take a pause right here any questions comments any thoughts feel free to interrupt me as a prophet as well all right I think we'll try one more example and then we'll talk at a little bit higher of a level markdown underlined this is one that I really enjoy so we'll close out this example don't care about those changes and we have another example where you have two sets of files and I want to capture off that same functionality so I'm going to do this one a little bit quicker but I want to show you the same sequence going on I happen to know that for markdown you can use a sequence of equal signs to represent a level one heading same thing here a sequence of dashes to represent a level 2 heading so I want to be able to capture that off so again what I'll do is I will record my actions making those changes in them so QQ to start a recording of a macro ganky IG key for paste Big B for visually select the whole line R to replace the equal sign so now I've replaced all of those q to stop recording and now again I've got that code available to me if I know no leader u1 normal you can see it above so you know what I'm getting to but there it is jump back out so the idea building up one of these little bits of functionality is that straight forward and then over time you get to iterate and iterate so you can see below this is the function that again actually lives in my demo to see that I use everyday if I want to underline with level one I have a mapping eater you one that calls this function now with an argument it was slightly more complex but the sort of thing that you can easily learn over time if the level is one we use an equal sign at the level it's two - and it turns out that level three headings in markdown are a little bit different so for those big items started to beginning of the line and then three pound symbols so again I've got that condition listed as well so now I think we've laid the foundation of how do you capture this functionality how do you put something into your vim RC that you can reuse so now the next question is how do you share this with someone it turns out it's very simple I actually went through this very recently and let's go back to here so I recently extracted a plug-in from IBM RC so I've gone through this exact sequence and here you can see the very simple outcome of that I produced a readme in this folder and I have a plug-in folder and that is the secret right there then when it looks for code to execute is looking for a number of aimed folders and it will execute any file within those named folders there's a little bit more logic behind it but for me almost every time this plug-in folder is the secret so I pull all of the code out of my MRC I put it into a plugin file the plug-in file convenient anything doc then and then I have all of the code in there this is one that grew over a very long time so it has a number of lines but it did start the same way I captured a sequence of keystrokes and then I made the functions a little smarter a little smarter a little smarter now I've extracted that out and expose it in a way that anyone can install and use the last bit with that would be the use of bundle as ever when you're used bundle is everyone familiar okay for those of you are and I'll give a quick overview bundle is a package manager essentially for bin and it allows you to install based on just a snippet from the github URL so they're generic bundled up and that's the way you would say this package and then it loads them all into a particular directory so for me that directory this is going to look a little bit weird on this screen but for me that's been slash bundles and each of these is a different git repository that is a plugin so this is how people can use that get repo that you've put together this gets installed on their machine and now whenever BIM starts up bundle will make sure that this code also gets executed and the same rules apply as long as it's in a plug-in folder you're good to go so every one of these have that sequence going on so I have a few additional tips and techniques for plugins stuff but again just want to see if there's any questions anyone else has yes when I've recorded the macro how do I print that that's ctrl R which will hop over here into them I'll close this up for now H see if I can find it in the docs yes here it is so this is ctrl R it is an insert mode command and it's insert the contents of a named register this is actually a control version but don't worry about that so as I'm typing an insert mode I type ctrl R and then Q because Q is where I put all of those keystrokes I told it to record into Q and later I can get it back from Q but ctrl R can actually pull from any register you can actually see all your registers by typing registers and here are all of the things that I have copied and pasted recently most of them up at the top the 0 through 9 are your recent Yanks but down here are more purposeful ones where I've actually captured a few things so that's that's how that goes control are any other questions so you can edit a register so a register is just a collection of characters so you can dump it out and we'll go ahead and do this I'll edit thing them here so I'll enter insert mode and then control our queue that dumps out the most recent thing that I recorded which is apparently BD and P up to there say I didn't want to do big P which is what I have right now instead I wanted little P so now I've edited this and then I can say quote Q yank inner word so that says yank this into register Q so quote and then a register name which is anything a through Z it can be prepended to a lot of things so you can say paste from or record into or mark as any of those can target them and in this case so now if I come down here control our queue that's a little bit weird I yanked inner word small word which this curly brace was a delimiter fork to do that correctly it would be big quote our double quote q yank enter big word and now I've got it so I could grabs that but basically you're yanking into a name register there are other ways you can have commands that say set register equal to this but this is the very thin way into this do this action any other questions alright now it's going to pro tips crazy I know ah let's see them read me so I guess a question is what can you do with plugins what is kind of the range of things that you can raise of ways that you can change them that you can update them you can add functionality turns out there a lot of really cool ones so I've organized a couple of groups here to represent some of the different things the first our custom text objects so Mike did a great job earlier of talking about the flexibility of them and how it's got this language and you don't to memorize things because you've just composed a command and this other thing that other things a text object so when we talked about I paren that is a text object that says inside of the parens I capital W that I just used a moment ago was inside a space delimited word and there's all different ones that come with them but these are a few that you can actually install and extend them so for instance this one text object indent allows you to treat common indentation blocks as a bim targetable thing so for instance this sequence here in this text document is otherwise not really targetable but with this plug-in installed you could say d a I delete a indent and it would know how to do that you can extend bins vocabulary which to me is like the holy grail the same thing this is a plug-in from juniel is the author of M casts that does custom text objects for Ruby so it says you've defined a ruby method I now know about that you have a ruby block you can dar delete a ruby block and you know have these custom ways to talk about the different things and these can be extended you can add new ones if you have a particular language that you like that doesn't get the support you want and then you can teach then it can learn it's an old dog but it can learn new tricks similarly so those are the nouns and vim sentences those are the objects that you're talking about you can also add new commands so those first two were not actually mine but the rest of the plugins I'm going to talk about our mind I've created one called title case which allows me to operate on a region of text and title case it so in this case I'm inside of a word I can say GTI W and we'll title case inside that word the same thing can happen if I jump see I lower case that line for demonstration now if I want I can say go title case enter line and I can title case this whole line which for markdown documents turns out to be really useful similarly I can say title case inside of a string which is very often a thing that I need to do so title case is a plugin that allows you to do that and again you can see the same sort of functionality here have a simple plug-in folder that contains all of the magic sort motion is another similar one it allows me to sort given lines based on a motion so I can say I don't know if I have a great sort example in here we come down to these I can sort these lines alphabetically by saying GS ap which sorts a paragraph so GSI P will do the same thing it actually reads in those sorts them and then drums drops them back in and it can also sort based on arguments going into a function so those two things the idea of being able to add new words to the vim dictionary and new commands that operate on those words there's kind of exponential awesomeness coming out of that because you can combine them with everything that exists and with each other and it's kind of Awesome yes when you see words yep the words you're specifically using are yep so nouns in general when you talk about them encompass both motions like J is down and text objects so these are technically like the text object things but they are very much the nouns in the bim sentences and then the commands are the they're the verbs so title case inner indent is an example of a custom command operating on a custom text object teaching bim something much more powerful than what it had before it's really awesome stuff additionally there's a lot of other things you can do i have two plugins that particularly deal with tea mucks i am a tea mugs user and i love it the two of them are tea mocks navigator and tea much for honor team ox navigator allows me to split up my window all of this is tea mug stuff over there is my bin window and i can now move between them all as if they're one kind of continuous thing i'll split this open that's ignored split that open now I can move up with the same sequence of keys for me it's control hjkl and those allow me to move all around the world as if everything is just one big continuous thing it's the closest thing to getting an IDE in your shell that I found that I really want an IDE but that functionality of kind of blurring the edges turns out it's really useful at least for me I used to just hit the walls all the time and get really angry similarly I've built up a plugin that allows me to communicate from them over to team ox so what I can do here is I can attach so there we flash the numbers real quick so I'm attaching to pain one here and from inside of them I can say echo hello which obviously doesn't work in vim but now I can shoot that across with ap command and that will run over here in two months this turns out to be really useful for test running for developing interactive scripts for playing around with an API and again this is the sort of thing that you can do in vim this involves basically connecting to the UNIX underlying stuff there's a piece everything else is a piece and they can talk because they are UNIX yeah I didn't know if I have prime developed Ruby in a while so here's pry and prized a ruby repple so it's a way to evaluate Ruby code interactively so I can say puts hello for the same sort of thing but it's now going over to a ruby interactive session I can do that this can run say on a per oku instance if you're connecting with your remote servers you don't have a way to upload a script well you can just write it locally and send the lines across which at one point in my career actually saved the day so it was cool to three lines five dot time so I know how to do this do this is there right away yeah I think so there's like a variable here and stuff puts I and that seems like Ruby so VIP select the inner paragraph and then I can send those across and so we get first the hello and then we get that block evaluated five dot times do and then the sequins are coming out first I'm sure this yeah things very amenable to these sort of changes then in team ups actually work really well together but that's one of the things that I do love about them I'm going to try and clean this up a little bit so it's a little more readable there we go vim is very amenable to change and them is a really good UNIX citizen so don't worry if you don't really know UNIX that doesn't matter the idea of UNIX is that it's small focused tools that do one thing extremely well and then can interoperate by sharing texts around and then is great at that and T MUX is also great at that and Akkad said and pry and all of these other tools are great at what they do and by leveraging them for BIM stuff and other tools for other stuff and connecting those together turns out is really awesome so that's an example of kind of system integration stuff these are two different cases where I've connected to Team ups but you can go a lot bigger than has a system command it just basically does something in your shell and that can be anything which is pretty cool lastly I have a section that I ridiculously titled raw efficiency and now regret that but what can you do look at me the first one is a spec runner so this one is very similar to BIM our spec which Mike referenced earlier but this is a little more general it's not complete yet it's something that we've been working on but it allows you to run JavaScript tests or Ruby tests or really whatever you need and the coolest thing is that we actually did it with test-driven development which was crazy we actually wrote a blog post about that robots yeah no no this one so there's a whole blog post about how we wrote this using a wonderful gem that lets you interact and write tests around your bin buggins it's kind of crazy but it was kind of awesome but so this is a plugin again that does general test running what else do we have I have a plugin that I've written that helps with navigation using Factory Girl Factory Girl is a test helper library that we use in Ruby and rails and this is something that allows you to navigate between files really quickly I have one for managing git merge and rebased conflicts just helps with showing you the diff interacting with the different pieces moving through them and the coolest one that I just made the other day um is a thing called quicklink which I'm going to demonstrate right now for fun I can highlight the words get here and I want to get a link particularly a markdown formatted length to that word so what I can do is visually highlight it and then hit the key which in my case is control K and now git will pop up the thing that I highlighted but I'm going to add a little bit to it just say get SCM and there it is get SCM comm that's the link that I wanted these are the first four Google results they're in a list for me I can shift in tab through them and when I could enter will actually put that link in line actually add the other bit down bottom and again this is using that same sort of stuff it shells out to another thing that knows how to talk to Google gives me back the results and then I work in bin because that's where I can manipulate text and do things yeah it's pretty good that was doing I know all the time this one took me like four months to create and then recently I was showing it someone so this lived in my MRC and brew and grew and grew over time exactly the way that I showed at the beginning and only recently to actually pull this out I let I took my time to take the time to automate it this one clearly is a win now plus a really like writing bin script so I can just write it all off as like happiness time for me that's my theory on it so that's I think most of what I want to say that's an example of what you can do I've got some pro tips down here they're a little more advanced stuff I'll add some notes into the repo but I don't know that it's necessarily the best stuff for me to go over right now by all means we can chat after this but before we finish up any other questions everyone inspired to write a bin plugin awesome well thank you guys so much for your time our question yes yeah and I yep I have an issue open for that so them has functionality for creating those sort of command things and basically you write a function in bin script that takes an input modifies it and then replaces in some way so the answer is you could definitely do it I've been thinking about it's probably going to be just a list of blacklisted lowercase words and then everything gets piped through that but that's the thing you can arbitrarily kind of build these things up and title cases very amenable to that I've just been lazy I'm okay with being kind of iffy and my prose I mostly write code so I find a compiler all day or an interpreter I don't want to fight prose but yes you can definitely do that any other questions awesome I think that'll round out and meet up for tonight you guys are welcome to hang out for a bit have a few more beverages we can chat that sort of thing thank you very much for coming other thing if anyone is interested in I guess any suggestions any comments any criticisms of the Meetup I'm very open to those I'm now the official owner of this thing so yell at me that seems like the right thing to do additionally if everyone if anyone wants to speak at an upcoming BIM meetup we're always looking for people you can talk about just about anything the schedule is I'm sorry very rate um yeah I mean if I if I had more speakers I think I'd probably push it a little bit more we usually in theory I want to aim for probably once every two months so if we can go for that I think that'd be great I'll also try and schedule one in the near term that will be more kind of an exercise sort of thing we did that a few years ago I think it worked out well so we'll probably try that but would love if anyone would like to give a talk or if you're interested in the smaller talk let me know maybe we can rank tonight of lightning talks MRC show-and-tell that kind of thing but interested in getting as many of you folks as possible up here and sharing with the rest of us and really share what we all know so again thank you very much and you

Channel: thoughtbot

Views: 47,839

Rating: 4.9444447 out of 5

Keywords: Vim, thoughtbot, meetup, boston, Plug-in (Software Genre), Software (Industry)

Id: lwD8G1P52Sk

Length: 36min 38sec (2198 seconds)

Published: Tue Sep 16 2014