TakeTuesday E01: nvim-cmp

yo what's up youtube it's me tj with my new series take tuesday it's a chance for us to learn about new neovim stuff yeah so it's what we do on stream on tuesday mornings and we're gonna be like i mentioned learning about existing plugins that i already use maybe i don't know how to use them very well or exploring completely new plugins that i want to put into my workflow and we'll be able to share all of that with you as we go so with that why don't we climb on in for this new series take tuesday what's up youtube welcome to the very first take tuesday this week we're going to be talking about envim comp and actually this is sort of just a general guide towards what my current autocomplete sort of setup and experiences within neovim we'll talk a little bit about where i came from before why we're here on envencomp what i really like about it we'll explore how you can do some of the really simple configuration really simple setup we'll move into some options that i think are really helpful in sort of customizing the experience to be just the way that you like it and then we'll sort of wrap everything up with building our own example source for envencomp that can do stuff like complete issue numbers from github depending on which repository you're in so it'll just be kind of like uh we're gonna work through it talk about it and hope you enjoy it if you do enjoy this style and there's other plugins that you want me to do please comment or contact me on twitter or whatever i'm really looking for feedback about this new series that we're trying out so with that let's go ahead and get started so a lot of you know that at one point i was using completion and vim this was probably one of the very first lua async style completion frameworks that are sort of this in this new batch or new generation of lua plugins for neovim over time both there was a difficulty with we didn't have someone that wanted to maintain the project as well as the scope became too large so i actually have moved off completion and vim for quite a while by the time that this video came out i actually moved over to and then comp e so notice this is c-o-m-p-e and this became a in a lot of ways the de facto standard for a lot of people that were playing around with this but ultimately the author of this plugin recognized that there were some i will say mistakes because i think uh the solutions made in nvim comp are much better than this but effectively lots of problems were things like sources had to be defined in certain places it wasn't very extensible it encompassed too many things in one repository which made doing things like maintenance and bug reports and reproducibility really difficult uh and so actually the author eventually deprecated nvm compy so if you're looking here you'll notice that henman copy is deprecated and now we get to where i am today which is on envencomp here's just a really short list of the features of envimcomp i think sort of the best parts about nvim comp are this idea that most if not all sort of configuration points can be customized via lua functions which lets you sort of really customize and create an experience that's exactly the way that you want and additionally this auto completion plugin was really designed with a lot of the features that are required for a proper lsp experience which also just happens to sort of create then this really nicely architected well-rounded well featured plug-in that allows you to do sort of any of the things that you'd expect from a modern auto completion style plug-in and the last thing that i personally love about nvm comp is that the main repository the main place where the development's happening is just the engine for doing all of the interesting things for completion so it doesn't try and implement a bunch of different sources right here which as we go through you'll see that you know you have to install a few more plug-ins to get started but i think that this style and architecture works really well for auto complete sources if you don't like how nvim comp decides what buffer words to suggest or things like that well you could just write your own plug that in over top and allow that to happen and the other nice thing is that this really lets the ecosystem sort of evolve as it's going to make sure that we're picking the best things and the best things for you going forward and that's one of the things that i really have fun playing around with in the open all right we got some code i know that's why everybody's here so let's try and work through this right the first thing you're gonna need to do and all this by the way is detailed in envencomp's readme super detailed very easy to follow i think but we'll just walk through how i've got it in my setup and of course i will post links in the description below classic youtuber style of course by the way this time where i'm gonna mention if you're not subscribed feel free to subscribe if you haven't hit the bell smash it and of course feel free to click that like button as well moving on we'll need to install nvim comp as i mentioned this part of the plugin is really the core engine this is what does all of the really interesting bits for envencomp as a whole however what you'll need to do in addition to that is install the sources that you want if all you did was install nvim comp you wouldn't be getting anything interesting coming out next what you need to do is install these other sources and you don't have to install all of these but i'll just walk through what each one does and vim comp buffer basically completes words from the current buffer that you're in so this is really nice for completing things even when sometimes you don't have autocomplete or you want to complete something in comments all that kind of good so far you're writing markdown stuff like that comp path is a plugin to help you complete files so it'll just detect when it looks like you're typing a file complete those for you and vimlua is actually a really cool one if you're writing lua or doing lua development for things because it basically has a bunch of special neil them knowledge and and will apply really nice completions for example we can see something like this where i'm actually getting completions for all of the different api functions so that's super nice um and then the next one that i think is very very important for anybody using built in lsp is to get comp and the mlsp this is where things start to really shine i'll show a few examples later but this is how you can get super easy auto import on complete if the lsp supports that of course as well as doing other things just like moving between snippets expanding snippets things like that the last thing to note and this one this plugin here will differ depending on which uh snippets plugin you use i use lua snips and i do hope to make a take tuesday about lewis nips at some point in the future but comp doesn't ship with a snippets sort of execution engine plug-in whatever you want to call it that actually relies on other people to do that so you'll have to install whichever snippets plug-in that you want to do and then you can do that so i'm using lua snips so i installed this plugin all right sweet so we've got all this stuff installed what comes next well what you're going to need to do is you're going to need to somewhere in lua code either in your init.lua or some lua required function or within a big lua block inside of the net.bim either way will work is you'll need to start doing comp setup so comp setup is sort of your hub or home place where you're doing all of the configuration for comp a bunch of the different mappings are described in the readme the important ones for me are doing things like doing setting up something to do confirm this will tell copy that it needs to do stuff like apply those additional text edits you could be getting from the lsp when you're completing or other items like that i know that many of you out there like to hit tab and have that do completion now i'm not saying you're wrong but i'm just saying that that's not how i do it and i think it's bad and it's wrong anyways uh so if you wanted to do that it's quite easy to do you can read about a little bit uh in the readme i have these snippets available in in sort of my configuration for if you wanted to just basically copy paste these to work for you and you can do tab and shift tab to move between the next item and the previous item my only my only hope my only ask is before you copy paste this please at least just read helps ins completion because it gives you a lot of really great info about things that are just built into vim or or neovim for that matter and that you should sort of know generally this will work on any machine anywhere etc so they're just good things for you to learn and to know about so if you don't you should just take some time to read that and then i will allow the tab shift tab stuff to be applied but it will hurt me so now that you've got your mapping set up the very important next step is you need to tell comp what sources to use now remember comp is sort of like this engine or architecture sort of idea that other sources use to provide their completions so what you need to do is you need to tell nvim comp which sources you want to enable globally we'll talk in a little bit about how to enable it on a per buffer basis but you want to do these sort of globally and set them up so that as soon as you start typing you can get that auto complete going once you do that there are a few things that you should know about how these sources are set up so i thought this was super cool which is that the order that you put the sources in is actually sort of uh an automatic ranking of priority of where you would like these completion items from each source to show up so if you want sort of for me like vim.api sort of completions to show up before uh just words from the buffer like this then you can put it higher in that list you can also optionally specify the keyword argument sort of priority and set some number like 50 or whatever and you can manage that yourself but i've found just doing this sort of ordering works just fine for me another really cool thing that you can do is you can set the keyword length argument here when you're inside for each source this is really nice because when you start typing something it won't start suggesting those things until you've typed enough letters so if i'm inside of a comment here and i start typing something like key notice how i don't have completion yet i actually don't want completion for when i've just typed the first few characters right but as soon as i cross five characters which is my keyword length it's going to start suggesting things from the buffer i find this really nice because a lot of the times i don't want the window to open or close or do all these other things i i know what i want to type for short words but once i get to these longer words then maybe i'm going to have a typo or going to do something else dumb you can do that so that's a really nice sort of configuration point that i'd like to point out the other one that i don't currently have on any of mine but it's also possible to do is that you can specify the max item count for something so if you think that like you're just getting tons and tons of options from one source but you don't actually want that many you can set max item count to limit that and maybe that'll bring less clutter to the completions that you have i think it's possible that more will come over time but these are just the ones at the time of writing that i thought are interesting to share with all of you another thing to note as we're looking through this is that this anvim lua source understandably you might think well isn't that only useful inside of lua functions or inside of lua files and yes that's true it is but actually the source itself knows that it's only useful inside of lua so it only enables itself inside of lua however if you were looking to do that yourself you can actually do something like this where you set some auto command and a file type and then you can say require comp setup buffer this is the important part you can call setup for a buffer and you could say additional sources that you would want to run now note this is additional sources the global ones will still be available so you don't have to like redo the list every time you just go right ahead and say the sources that you want to add so you could add enven lua in this case i left mine for on all the time because the source handles itself but i just wanted to make you aware that that's a possibility for both and now since we've been talking this whole time you're probably wondering hey tj what's this gh issues one well we're gonna get to that one later you'll just have to wait till the end of the video next up is snippets and you don't have to do a whole lot to get snippets working for nvim comp but the thing that you need to know is that you do have to have some snippets plug-in and that there's a little sort of tidbit of code that you have to put in if you're doing lua snips then this is all the code that you have to put in to basically get snippets enabled inside of nvim comp i i think there's stuff for vsnips maybe ulti snips i don't know but i imagine it would be incredibly difficult to add some of those things so if you're using nvm comp and you have snippets and you want lsp snippets to get expanded correctly you need to do something like this at some point i think there's recipes in the readme you can just copy paste any of those for whichever snippets plugin you are currently using one thing that i thought was super cool is that you actually have the ability to sort of change the formatting of each source and the way that they show up and do all sorts of different and interesting things i have to plug in lsp kind which i'll also link in the description which allows for sort of these really nice uh you know bonus sort of colors here and icons that i think are pretty with some bonus information but you also note that i get this i'll call it like a source marker or a menu item for where this is actually coming from and you can customize that as well using alice be kind there's not too much to it and there's a snippet that you can once again copy and paste or you can copy and paste from me but the thing that's cool is if you wanted to say some different name or different thing or you wanted to add your own different menus you can see where each source is coming from which is good for doing things like selecting a completion and making sure that you're not just picking some word that's in your buffer but they're actually picking like the lsp suggestion that you expect to be getting uh when you're typing so that's really nice and i like how this is sort of all just lua functions all the way down where we're able to add these customizations to look exactly the way that that i would like or that you would like instead of trying to just figure out what the one way for everybody would be all right at the time of this video there are two experimental features i love the new menu this is not actually the normal completion menu a bunch of work went into doing things where you sort of get this beautiful new menu that's floating with additional abilities to add extra highlights and we'll talk about custom those highlights in a moment but so i turn off the native menu and i'm using the beautiful new menu that is the default i imagine over time this menu option may get removed but i really like the way that the menu is uh now with the sort of new non-native menu the second experimental option that i thought was really cool i haven't decided if i love it if i'm going to keep it for a long time or not but it's this ghost text api and what you can see is that actually like as i'm typing it puts neovim's virtual text in this area here but that's not actually inserted yet into the buffer so this is really cool for just looking sweet i guess um i i i turned it on because i think it looks cool i'm gonna keep it on for a few days and see maybe next time i'll let everybody know what i ended up choosing to whether i'll keep it or not but i just thought it was really cool to be able to do this and so i left it you might think it's cool or you might think it's not super easy to turn it off on and off with this flag all right here you'll see that here's an example of me turning on a particular source within different file types so sql mysql pl sql any of these different kinds of sql files i turn on vim dad bod completion very cool plugin you can check it out the link will be in the description as well but this is just a note and an example for all of you if you look in my doc files later you will be able to see how i'm doing sort of this conditional file type only configuration one other thing to note is that it's possible to disable very easily for different file types or under certain events uh nvim comp all you have to do is actually call requirecomp.setup.buffer and set enabled equals false and that will immediately turn comp off for that buffer so this is useful for things like telescope but nvm comp already knows not to turn on in telescope via some settings that we set in telescope so basically we're playing nice with each other the way it is right now but if you needed to do that or it wasn't working for some reason you could add this additional auto command to your setup and that'll confirm and make sure that mncomp doesn't turn on in those kinds of buffers all right last up in sort of this just config section is talking about being able to do different highlights i think it's pretty cool you can actually customize each of the different things in the window for nvim comp to give exactly the sort of appearance that you want these highlights are listed in the readme at the time of this video these are the only ones available i'm using a plug-in that i wrote a while ago called color buddy to sort of wrap some of these apis and make it a little bit easier for me to write but it's very cool because this means you can do things like highlight deprecated things different from regular suggestions you can do different kinds of text for uh the suggestions for when i type group we see how this is like purple right now if we change this to be something like error this is a the error group so it'd be linked there group and we run this and i do group notice how this change so you can pick whichever colors work well for you i like these colors so far i might change them around as i'm exploring but i i found that this is quite nice sort of hiding this menu part in the background but still visible and doing other parts with this is sort of just the normal color that i have for everything else so that's the last of sort of the basic configuration the basic things that you can do to really easily start making enven comp look exactly the way that you want it to look alright so before we get into showing exactly how you could make your own source i just want to highlight a few of the very cool and interesting features that you sort of get just as soon as you've configured on vim comp now of course the main reason the main reason that i'm showing this this is a rust file i write rust now if you didn't know you can come check out on the stream i've been writing rust for almost a month now i'd say and it pretty much defines my life i can't talk about anything else and i have to make sure that rust is probably mentioned in every video going forward sort of like contractually but anyways the cool part about envimcomp is you can do something like this let's say you're defining some new function and you want to return a hashmap okay right so this is a hashmap this is the standard collections for it i don't want to have to type anything else so what actually i can do is i can accept this answer for me that's control y you could make it whatever character you want maybe enter or anything like that and when you accept that notice that now at the top of the file that import was just scooped right up and added there so there wasn't anything extra i had to do that's working through the lsp and the lsp basically sends additional edits that the completion engine should do if an item is selected so in this case that was adding that hashmap so i think that that's just super cool and a really interesting thing that makes me a lot more productive i hate having to pick out uh or like go and write those different imports or anything like that if the lsp can do it for me then i'm happy to let it do that work so that was the first part right was this ability to add imports the second thing is that because comp integrates well with snippet managers you can actually sort of use snippets that come back from the lsp about edits that you should do so for example if i wanted to map and i wanted to insert something into this map i actually get a function that has k and v right so you'll see that i can put in a key and a value right and the ghost text is showing what's going to be there so i i kind of enjoying that ghost text i think it's good so far so if i accept this completion notice that now we've inserted the k and the v and my cursor is on the k right so um i can't point that far it's this way but it's on the k now so if i put 5 here i can press my jump to next thing in snippet button which would be whatever it is for you and notice i go immediately to the v and now i could type 10 i can say go to the next thing now i'm at the end of the line and i can just press this and continue moving right so i really like how envin comp integrates so well with my existing snippet manager i didn't have to learn new keyboard shortcuts i didn't have to do anything else none of that good stuff i just used and reused the same mappings and everything that i have with my existing snippet manager and cop uses that snippet manager to parse and expand the snippet that comes back from lsp so i think this is really helpful and i use this a ton for when i'm calling methods that i'm not as familiar with or other things like that where i need to move through it's really helpful okay before i show you how we're going to do this i just want to show you what we're aiming to do this is a pretty cool thing i think because it just shows how easy it is to start extending nvim comp into doing things that work for you the way that you're hoping for to make you a little bit more productive just and also to have fun which is always one of my mantras for working in the event right so in this case i'm inside of a git commit buffer here i'm about to make a commit and supposedly in this case i fix an issue now usually that's not the way it works obviously i'm usually creating issues but let's suppose in this hypothetical universe i'm actually able to close an issue i could do is i could type closes and then when i type this octathorp notice that i get a list of the open issues inside of this repository when i cycle through them i actually see the title and the body of that issue so i can make sure that when i write closes and i put this into my commit message it is actually the one that i want to close so that's great and then i could write more info here etc so that's what our goal is that's what i'm going to show you how i created and just using very very simple code for nvm comp and literally just under 70 lines of code so it's pretty exciting let's hop over there all right so we're going to walk through how we created the source and i think you'll be surprised hopefully pleasantly at how easy it is to make a new source i could imagine actually creating several of these for just different situations where i find myself repeatedly do doing something where i know that there is a programmatic solution to select from one of some items right so i think this is really nice to know how to do and we're just going to show you how to extend so what do you need to do to create a new source basically what you're going to do is make a new lua we'll say object but it's just a table with a few different methods that need to be there the first thing is source dot new this is very simple just returns a new object you can do any initialization you need to do here if you want to add caching or fields or anything like that this is where you would do that the main sort of meet or the big bulk of what we're going to be doing is inside of this complete function this gets called by nvim comp and calls your source and asks for the results but instead of sort of synchronously grabbing those results what envencomp does that's very nice is it gives you this higher order function basically just this callback that you can call whenever you have results to give so this is really nice because what we can do is we can actually run an executable make some requests and when that request is done we can call the callback with the appropriate items so that's what we're going to do we do a little bit of it's not strictly necessary but it's just nice if you're going to make a request to someone else's api just consider caching it if you know it's going to be the same like all the time so we're just gonna cache it basically for this you know one session to make sure that we're not constantly constantly asking the same question to the api in the not cached case what are we going to do we're just going to ask github hey can you give us the issues list them i just asked for the top a thousand if you have more than a thousand open issues you could change this number or you could make a dynamic or whatever you need to do we asked for the result results back in jason because that makes it much easier for us to parse and then we just ask for the field's title number and body because we don't need any of the other fields like assignee you could imagine doing this or even filtering by issues that are assigned to you or whatever it is but i didn't think that i needed to go there this provided plenty of good stuff for me and was already plenty fast enough so i'm using plenary's job api but you could do this with job start or other things as well if you really wanted to it's not super difficult to imagine how you do that so what this does is this function runs when the job exits we can get the results we try and decode them if that fails we just short circuit out nothing crazy there so up to now we haven't done anything very exciting in fact we can show exactly what we're doing if i went to here and i ran gh issue list a thousand we can see exactly what the result would look like so you could test this out outside of neovim outside of here just making sure that you're getting exactly what you want once we do that we just collect a bunch of items which for us means we're going to loop over this list of json values that have body number and title and we just need to put them into a format that and vim alice or that and them comp can understand so what we do is we just make sure that we don't have any random character terms that we don't want we put these items inside of here we can put a pound sign in front of the label the octathorp if you will just so that it looks exactly how you'd normally write an issue number inside of github or something like that we add this bonus documentation and envimcomp handles all the difficult annoying stuff about formatting that making sure to apply the right file type if applicable all this other sort of stuff all i have to do is say what i want the label and the documentation to be and then vimcom will handle the rest we call the callback with these items and then we just catch the result we don't have to cash but like i said i think it's good practice for us to be able to do that and that's it that does all the hard work once you implement this var when i start typing it will go and search for things that map and nbmcomp handles putting these into the same thing sorting on priority etc etc i just had to write this little snippet of code there's a couple other cool things though that we do further down in this file the first one is that we add a trigger character which basically says only trigger this completion when i type these characters or some patterns that match these characters in this case i only ever want to call this completion when i type an octathorp because that's the only time that i'm ever going to reference issues other times i don't need it so this makes it so that you can control that on a per source basis the other note is that you can control when sources are available and i automatically made it so that we only turn the source on when the file type is set to git commit so with all these things together the very last thing that you need to do is just register the source with a name and then call source new which basically just says hey give me that new thing that i need to be able to call after we do that we're all done and that gives us exactly that experience that i just showed you before to be able to complete the issues and show all the documentation you could totally imagine extending this to do pr numbers if you wanted for when you're making comments or or anything else like that i'll probably write some more for myself as well all right and with that that's the quick overview the general overview of nvm comp honestly i've been super happy super pleased with the plugin i've been having a lot of fun it feels fast it feels responsive it feels configurable it feels complete a lot of it just feels really really good i really highly recommend this if you're not interested in trying this one out there's another really interesting plugin called coke nvim which is actually different from coc and vim coke envim is another completion engine that's out there that i've heard really really good things about it's very fast very quick and a lot of people like it a lot so you could consider trying this one instead for now i'll stick with nvimcom because i'm enjoying it you could also try coc.nvim if you're not interested in any of these or you want something that works with vim i really hope that you found this tutorial helpful if you have any questions feel free to comment below if you have any suggestions for other plugins let me know if you liked or didn't like this format also please let me know mostly what i'm looking for is just some feedback to make sure that i'm hitting exactly what you're looking for that you found this useful it takes a while to put together these videos and all that good stuff so i want to make sure that i'm helping the best that i can anyways i hope you enjoyed take one of take tuesday and feel free to stop by on twitch tuesday mornings eastern time to learn some more about plugins with me as we explore thanks everybody i hope you have a great day keep on neo vimin

Channel: TJ DeVries

Views: 42,252

Keywords: Programming, Neovim, autocomplete, nvim-cmp, lua, init.lua

Id: _DnmphIwnjo

Length: 30min 41sec (1841 seconds)

Published: Thu Oct 21 2021

Reddit Comments

[u/RemarkableBroccoli84]

Teej, if the good lord didn't want me to use tab for completion, he wouldn't have made it feel so good!

[u/rockerBOO]

https://i.imgur.com/KvpHrx4.png Highlight map for nvim-cmp for styling purposes. I use some modifications so your results may look different.

[u/kjnasdfjnpkl]

I've been using nvim-cmp for a bit now, but when I started I really struggled with the documentation, which seemed to just mention everything, but not clearly lay out how to simply get started.

But since TJ said it was easy to follow I took another look and it seems very much improved. Props to the contributors!