#macvim

Our beloved Vim offers some possibilities to create and use menus to execute various kinds of commands. I know the following solutions ...

the menu command family

the confirm function

the insert user completion (completefunc)

I will not bother you with a detailed tutorial. For more information I always recommend the best place to learn about Vim - the integrated help.

:menu

Let's start with the most obvious one, the menu commands. The menu commands can be used to create menus that can be called via GUI (mouse and keyboard) and via ex-mode. A good use-case is to create menus entries for commands that are not needed often, for which a mapping would be a waste of valueable key combinations and which can probably not be remembered anyway as they are used less frequently.

I'll keep it short here and as there are already tutorials out there. And of course the Vim help is the best place to read about it. :h creating-menus

Vim offers several menu commands. Depending on the current Vim mode your menu changes accordingly. Means if you are in normal mode you will see your normal mode menus, in visual mode you can see only the menus that make sense in visual mode, and so on.

Let's say we want to have a command in the menu that removes duplicate lines and keeps only one. We want that in normal mode the command runs for the whole file and that in visual mode, by selecting a range of lines, the command shall run only for the selected lines. We could put the following lines in our vimrc.

nmenu Utils.DelMultDuplLines :%s/^\(.*\)\(\n\1\)\+$/\1/<cr> vmenu Utils.DelMultDuplLines :s/^\(.*\)\(\n\1\)\+$/\1/<cr>

The here used commands are quite simple. After the menu command you see only 2 parameters. First one is the menu path. I say path because by using the period you can nest your menus. Here it is only the command directly under the Utils menu entry. The second parameter is the command to be executed just like you would do from normal mode.

There are 2 special characters that can be used in the first parameter. & and <tab>. & can be used to add a shortcut key to the menu and <tab> to add a right aligned text in the menu. Try it out!

Remember that you can access the menu also via ex-mode.

:menu Utils.DelMultDuplLines

But please don't type all the text and use the tabulator key to do the autocompletion for you. ;-)

confirm()

The confirm function. Luckily I already wrote about this possibility. So instead of copy-pasting the text I just link to it.

vim-confirm-function

set completefunc

Let's get dirty now. I guess the insert completion pop-up menu is well known by everyone. But did you know that you can misuse it for more than just auto-completion? I did not. I will show you what I mean.

Usually the auto-completion is triggered by pressing Ctrl-n, Ctrl-p or Ctrl-x Ctrl-something in insert mode. One of these key mappings is Ctrl-x Ctrl-u which triggers an user specific function. Means we can write a function that does what we want and assign it to the completefunc option. Let's check what we need to consider when writing such a function.

The completefunc you have to write has 2 parameters. And the function gets called twice by Vim. When calling the function the first time, Vim passes the parameters 1 and empty. In this case it is your task to usually find the beginning of the word you want to complete and return the start column. One the second call Vim passes 0 and the word the shall be completed.

function! MyCompleteFunc(findstart, base) if a:findstart " write code to find beginning of the word else " write code to create a list of possible completions end endfunction set completefunc=MyCompleteFunc

For more information and an example check :h complete-functions.

Now let's re-create the LaTeX example using the completefunc. Here is a possible solution that supports nested menus, so for 1 level menus the code can be reduced a lot.

https://gist.github.com/marcotrosi/e2918579bce82613c504e7d1cae2e3c0

Okay let's go through it step by step.

In the beginning you see 2 variables. InitMenu and NextMenu. InitMenu defines the menu entry point and NextMenu remembers the name of the next menu. I just wanted to have nested menus and that's what is this for.

Next is the completefunc we have to write. I called mine LatexFont. As shown before it consists of an if-else-block, where the if-true-block gets the word before the cursor and the else-block will return a list that contains some information. In the simplest form this would only be a list of strings that would be the popup-menu-entries. See the CompleteMonths example from the Vim help. But I added some more information. Let's see what it is.

The basic idea is to have one initial menu and many sub-menus, they are all stored in a single dictionary name menus and are somehow connected and I want to decide which one to return. As I initialized my InitMenu variable with "Font" this must be my entry point. After the declaration of the local menus dictionary you can see an if clause that checks if s:NextMenu is empty. So if s:NextMenu is empty it will be initialized with my init value I defined in the very beginning. And at the end I return one of the menus so that Vim can display it as a popup menu.

Now let's have a closer look at the big dictionary. You can see 4 lists named Font, FontFamily, FontStyle and FontSize. Each list contains the popup-menu entries. I use the key user_data to decide whether I want to attach a sub-menu or if the given menu is the last in the chain. To attach a sub-menu I just provide the name of the menu and when the menu ends there I use the string "_END_". So the restriction is that you can't name a menu "_END_" as it is reserved now. By the way, I didn't try it, but I guess that user_data could be of any datatype and is probably not limited to strings.

Let's see what the other keys contain. There are the keys word, abbr and dup. word contains the string that replaces the word before the cursor, which is also stored in a:base. abbr contains the string that is used for display in the popup-menu. From the insert auto-completion we are used to the word displayed is also the word to be inserted. Luckily Vim can distinguish that. This gives me the possibility to display a menu (like FontFamily, FontStyle, FontSize) but at the same time keeping the original unchanged word before the cursor. This is basically the whole trick. Plus the additional user_data key that allows me to store any kind of information for re-use and decisions. With the dup key I tell Vim to display also duplicate entries. For more information on supported keys check :h complete-items.

Now let's get to the rest of the nested menu implementation. Imagine you have selected an entry of the initial menu. You confirm by pressing SPACE and now I want to open the sub-menu automatically. To achieve that I use a Vim event named CompleteDone which triggers my LatexFontContinue function, and the CompleteDone event is triggered when closing the popup menu either by selecting a menu entry or by aborting. Within that function I decide whether to trigger the user completion again or to quit. Beside the CompleteDone event Vim also has a variable named v:completed_item that contains a dictionary with the information about the selected menu item. The first thing I do is saving the user_data value in a function local variable.

let l:NextMenu = get(v:completed_item, 'user_data', '')

The last parameter is the default value for the get function and is an empty string just in case the user aborted the popup-menu in which case no user_data would be available.

One more info - this line ...

inoremap <expr><esc> pumvisible() ? "\<c-e>" : "\<esc>"

... allows the user to abort the menu by pressing the ESC key intead of Ctrl-e.

And last but not least the if clause that either sets the script variable s:NextMenu to empty string when the local l:NextMenu is empty or "_END_" and quits the function without doing anything else, or the else branch that stores the next menu string in s:NextMenu and re-triggers the user completion.

The rest of the file is self-explanatory.

I'm sure we can change the code a bit to execute also other command types, e.g. by storing a command as a string and executing it.

After finding a pair of settings in Spacemacs to enable transparency, I wondered if I can do something similar in MacVim.

Besides the search commands /, ? and *, g*, #, g# in normal mode where you can get the search pattern highlighted and can jump between findings with n and N, Vim can also present the findings as a list. Here are the built-in solutions I know about.

ilist

Run :ilist word, which is the short form for :ilist /\<word>/, and Vim will display all occurences of the word with line numbers. But if you want to search a more complex pattern than just a single simple word, you have to wrap the pattern with slashes :ilist /pattern/. Normal Vim regex rules have to be followed. Furthermore every line is listed only ones also for multiple matches per line. The interesting but also tricky part is that ilist ignores matches within comments unless you run it with !. This way :ilist! /pattern/ also comments will be taken into account. So ilist comes in handy if you don't want to be distracted with findings within comments. In order to jump to a search result line you can only use :linenumber. And to those who didn't know, the search result window doesn't need to be closed for that.

For more info type :h :ilist

internal grep

Run :vim /pattern/ filename(s) and Vim will create a quickfix list window (or a location list window if :lvim is used instead) containing your search results. Filename can be % for the current buffer or * or just some filenames or whatever Vim supports here. vimgrep lists each line only ones unless a g is used after the pattern /pattern/g. The cool thing is that you can jump to every finding, you can open and close the quickfix/location list anytime without loosing it and Vim also remembers old search results and you still have access to them. In my imagination the location (or quickfix) lists are of course below the current window and sorted from left (first) to right (last). As I don't use splits so often my Ctrl+[h|j|k|l] key mappings are set as follows

nnoremap <c-h> :lolder<cr> nnoremap <c-l> :lnewer<cr> nnoremap <c-j> :lnext<cr>zz nnoremap <c-k> :lprevious<cr>zz nnoremap <leader>s :call ToggleLocationList()<cr>

As you can see I have also a mapping for toggling my search results window. Here are some proposals for how to toggle the quickfix/location list window.

For more info type :h :vimgrep

external grep

The external grep is pretty much like the internal with all that quickfix/location list stuff, but all that is done with an external grepping tool as you can guess. The call is :grep [arguments] and the arguments depend on the grep tool you are using. By default it is the standard unix grep but you can change that. You could use any other tool by adjusting the settings grepprg and grepformat. Lets assume you have the_silver_searcher installed and you want to use that because it is so unbelievable blazing fast (probably black magic used to develop this tool), put the following in your .vimrc.

set grepprg=ag\ --vimgrep\ $* set grepformat=%f:%l:%c:%m

What a conincidence, ag (the_silver_searcher) comes with a vimgrep option which makes the integration quite easy. The backslashes before the whitespace indicate that Vim expects one string. The $* is probably all the arguments straightly passed to the external tool. And grepformat is for parsing the tool output. It tells Vim how the tool prints the findings. Here we pass --vimgrep as an option to ag and then it will use the format file:line:column:match and that's exactly how we set grepformat.

For more info type :h :grep

global

The global command :g can be used to run commands on all lines matching or not matching :v a certain pattern. But if you give no command to excute :g /pattern/, then global behaves as if you would give the p or # command, which simply prints the matching lines. Now this is what we already had with the :ilist! /pattern/ command, so why would I use this? Probably just because you can check, before executing any command, which lines would be affected and then recall the global command from the history and append the desired action.

For more info type :h :global

substitute

The substitute command actually does not list the lines containing a pattern but you can count how often a pattern appears in the text :%s/pattern//gn or on how many lines it appears :%s/pattern//n. Like the global command you can run the same also only for a certain range :'<,'>s/pattern//gn

Many of us have the problem remembering hardly used keymappings. For me there are only 2 ways of dealing with it. Either admitting that the keymapping of which I initially thought is very nice is actually absolutely useless why I radically remove it, or I realize the mapping is still handy but simply not needed that often. In that case I move it to my menus.

The menu command is probably known to most of you. That is why I wanna demonstrate an alternative solution by using the confirm function. Of course there are advantages and disadvantages for both solutions. I use both and not only for seldom used mappings as the first example will show.

Example 1 - Make Menu

All my makefiles have the targets build, test, tags, clean and some more. So I could have created mappings like ...

nmap <leader>mb :make build<cr> nmap <leader>mt :make test<cr> nmap <leader>mg :make tags<cr> nmap <leader>mc :make clean<cr> ...etc

My weak brain was not able to remember the shortcut for creating the tags file. So I came up with a solution using the confirm function to get a more visual feedback ...

https://gist.github.com/15e154f3aa0c31972aab

... which called looks like ...

... and now I can type the single letter representing the target I want to execute. If I want to abort I press the Escape key (confirm returns 0), and when I want the default target (in this case #1, calling make without target) I can alternatively press the Enter key. As you can see I needed an extra entry "abort" in my list to shift all other targets by 1, so I can directly use the return value of confirm to get the correct string for concat. Yes, I could instead subtract 1 from the return value when accessing the table.

Example 2 - LaTeX Menu

Nesting? Let's try. Here another example for LaTeX. I don't know if this useful, but it is just an example.

https://gist.github.com/3e13689d05a07b8297b8

Note that I set the FontSize default value to footnotesize (3rd parameter) because I wanted to keep the commands sorted by size.

And this is how it looks like. First you will be asked wether you want to set the FontFamily or the FontSize and then for the sub-values of the selected category. It works for the word under the cursor and for the selected text. Sorry for the bad quality.

For more information type :h confirm() inside Vim.

I had my first contact with Vim approx. 10 years back when I studied. In one of our C programming practicing lessons I asked my professor for help. He opened Vim on commandline and started typing. He was blazing fast with just two fingers. The characters jumped over the screen so crazy and I thought "Holy shit - how is he doing this, I don't understand". I just knew I loved it and I wanted to be able to this. A new nerd was born. I think three semesters later I had finally the time and chance to start using Vim during my practical semester. And of course you have to google a lot in the beginning and whenever I stumbled upon a good Vim site I saved it in my browser.

This is my Vim Link Collection in no particular order. Maybe you'll discover a Vim site you did not know yet.

Is there a cool site missing? Let me know.

vim.org

neovim.io

macvim-dev

vimdoc.sourceforge.net

vim-scripts.org

github vim-scripts

learnvimscriptthehardway.stevelosh.com

vim.wikia.com

vimrcfu.com

vim-adventures.com

vimgolf

openvim.com

vimawesome.com

vimgifs

vimcasts.org

vimninjas.com

shortcutfoo.com

vimregex.com

vi-improved.org

vim.begin-site.org

usevim.com

vim-fu

vim-galore

vim-bootstrap.appspot.com

dailyvim.blogspot.de

dailyvim.tumblr.com

derekwyatt blog & derekwyatt vids

rayninfo.co.uk

thomer.com

tnerual.eriogerg.free.fr

oualline.com

yannesposito.com

danielmiessler.com

cs.oberlin.edu

swaroopch.com

poho

vim.rtorr cheat sheet in various languages

vimsheet.com

graphical cheat sheet

vim cheat sheet for programmers

vim quickreference

...which are defined in .zshrc (as I am using zsh). 

ln -s ~/.zshrc ~/.zprofile

Part 1

For part 2 I promised a practical use case and I thought we could display some messages from a static analyzer (lint) like cppcheck or splint. Of course you could use a quickfixlist for that like you would do for the compiler messages, but the number of compile errors tends to be short, whereas the number of lint messages can get quite long - but that's a different topic.

First of all let's create some crappy code which produces some lint messages. Here are 3 pretty useless files - main.c, foo.c and foo.h.

Running splint gives the following messages (shortened)

foo.c:8:26: Variable Result initialized to type double, expects unsigned int

foo.c:12:11: Return value type unsigned int does not match declared type int

main.c:17:15: Fall through case (no preceding break)

main.c:19:17: Variable var used before definition

main.c:19:13: Return value (type int) ignored: foo(var)

The messages are in standard gcc format.

filename:linenum:colnum: message

I use signs to show in which line is at least one issue and balloons to show all messages refering to the line I hover with the mouse. E.g. line 19 in main.c ...

sign

Let's start with the signs. If you prefer pure Vim script then a possible solution could be ...

https://gist.github.com/c6af19db33d9af20880b

I mostly prefer writing Lua scripts and for debugging and test purposes I like to have intermediate files. Here is how I do it with an external script.

run the static analyzer and capture the output in a file

parse the lint messages file and create a Vim script file containing the sign placings with a "sign unplace *" command in the first line

run the generated Vim script with the :source command

Some lint tools distinguish between different types of messages. You can parse this information too and select a proper sign for each message type.

balloon

Next step is to create the balloon text. Therefore the filename and the linenumber in which the mouse is positioned will be used. Possible Vim script solution could be ...

https://gist.github.com/04d6d32cc7a6c5e56d8c

Now we have two functions - LintSign() and LintBalloon(). LintSign() could be triggered either manually or automatically e.g. after writing a file. The LintBalloon() function simply needs to assigned to balloonexpr.

autocmd BufWritePost *.c,*.h call LintSign() set balloonexpr=LintBalloon()

To get the same result but with an external Lua script I do something like ...

https://gist.github.com/c41b08945a162642c6ee

Do you know Vim's balloon and sign feature? There are some scripts which make use of them. For example the famous taglist.vim plugin which uses balloons to show the definition of a symbol, and most GDB plugins use signs to display the breakpoints.

I haven't seen many tutorials explaining these features, so I thought I could give at least an introduction. This tutorial consists of 2 parts. Part 1 will briefly explain how to set up balloons and signs in your .vimrc and part 2 will show an use case combining both features.

balloon

What it does is that when you hover with your mouse over a word a rectangle window pops up and usally shows some text. The cool thing is that you control what information to be displayed and as it is only a string it could be anything - spelling suggestions, the dictionary text or synonyms for that particular word, the documentation+examples of a function or whatever you can think of.

So how to set it up? Actually for balloon there is not so much to explain. There are only 2 important keywords you need to know. There is ballooneval and balloonexpr. We use set ballooneval to turn balloon on and of course set noballooneval to turn it off. balloonexpr is simply a variable you need to assign a function which returns a string. So whenever you hover with the mouse over a word and balloon is on then this function will be exectued and the returned string will be displayed in a box. Okay let's try this.

function! Balloon() return "hello world" endfunction set balloonexpr=Balloon() set ballooneval

So far so good. Now we will tweak the function a little bit and print some special balloon variables but of course you could use any available variable. For more information type :h v:

function! Balloon() let Info = "Window: " . v:beval_winnr let Info = Info . "\nBuffer: " . v:beval_bufnr let Info = Info . "\nLine: " . v:beval_lnum let Info = Info . "\nColumn: " . v:beval_col let Info = Info . "\nText: " . v:beval_text return Info endfunction

As you can see the newline character can be used too. And in case you didn't know, the dot operator concatenates two strings.

Now you can write your own balloon expression functions. Just create and return the string you want to display. And if there is nothing to display then return an empty string "", this way Vim doesn't create a balloon at all.

In part 2 we will invoke an external script which gets the information it needs to do something and it will return the string which Vim is then going to display in a balloon pop-up.

sign

Signs can be short strings (1 or 2 char) or tiny images which will be displayed on the left margin of a buffer. I will show you first how they look like, so that you know what I am talking about.

The image shows 4 different signs I defined and I placed them right beside the line which defines the corresponding sign. As you can already guess there is a command to define a sign and one to place a sign in a certain line.

hi red guifg=#F92672 guibg=#232526 gui=bold hi grn guifg=#A6E22E guibg=#232526 gui=bold hi org guifg=#FD971F guibg=#232526 gui=bold hi blu guifg=#66D9EF guibg=#232526 gui=bold sign define Error text=× texthl=red sign define Warn text=! texthl=org sign define Info text=i texthl=blu sign define Okay text=✔ texthl=grn

To define a sign you need a name (first parameter after 'define') and either a text (max. 2 chars) or an icon (icon=/path/to/icon). I think you can give a text and an icon and Vim decides automatically which to use. There are two optional arguments called texthl and linehl and both expect a highlight group name.

For placing a sign some more arguments are required.

sign place {id} line={lnum} name={name} file={fname} sign place {id} line={lnum} name={name} buffer={nr}

id is unique number to identify the placed sign

lnum is the line number where the sign will be placed

name is the name of the sign you want to place

fname is the file in which the sign will be placed

nr is the buffer number in which to place the sign and also the alternative to using the filename.

This means for the example above I used the following commands.

sign place 1 line=696 name=Error buffer=1 sign place 2 line=697 name=Warn buffer=1 sign place 3 line=698 name=Info buffer=1 sign place 4 line=699 name=Okay buffer=1

Instead of the buffer number I could have used the filename. The IDs have to be unique - no special sequence required.

To remove a single (id) or all (*) signs in one or all buffers use ...

sign unplace {id} file={fname} sign unplace * file={fname} sign unplace {id} buffer={nr} sign unplace * buffer={nr} sign unplace {id} sign unplace *