Debugging Vim Scripts

From TroubleshootingWiki

Vim

Source Book

ISBN	978-1-847191-44-1
Publisher	Packt Publishing
Author(s)	Kim Schulz

Sometimes things in your scripts do not work exactly as you expect them to. In these cases, it is always good to know how to debug your script.

In this section, we will look at some of the methods you can use to find your error.

In Vim, there is a special mode for doing script debugging. Depending on what you want to debug, there are some different ways to start this mode. So let's look at some different cases.

If Vim just throws some errors (by printing them at the bottom of the Vim window), but you are not really sure where it is or why it happens, then you might want to try to start the Vim directly in debugging mode. This is done on the command line by invoking Vim with the -D argument.

 vim -D somefile.txt

The debugging mode is started when Vim starts to read the first vimrc file it loads (in most cases the global vimrc file where Vim is installed). We look at what to do when you get into debug mode in a moment.

Another case where you might want to get into debug mode is when you already know which function the error (most likely) is in, and hence just want to debug that function. In that case you just open Vim as normal (load the script with the particular function if needed) and then use the following command:

 :debug call Myfunction()

where everything after the :debug is the functionality you want to debug. In this case, it is a simple call of the function Myfunction(), but it could just as well be any of the following:

 :debug read somefile.txt :debug nmap ,a :call Myfunction() <CR> :debug help :debug

So let's look at what to do when we get into the debugging mode.

When reaching the first line that it should debug, Vim breaks the loading and shows something like:

 Entering Debug mode. Type "cont" to continue.
 cmd: call MyFunction()
 >

Now you are in the Vim script debugger and have some choices for what to make Vim do.

The following commands are available in the debugger (shortcut in parentheses):

cont (c)	Continue running the scripts/commands as normal (no debugging) until next breakpoint (more about this later).
quit (q)	Quit the debugging process without executing the last lines.
interrupt (i)	Stop the current process like quit, but go back to the debugger.
step (s)	Execute next line of code and come back to the debugger when it is finished. If line calls a function or sources a file, then it will step into the function/file.
next (n)	Execute the next command and come back to the debugger when it is finished. If used on a line with a function call it does not go into the function but steps over it
finish (f)	Continue executing the script without stopping on breakpoints. Go into debug mode when done.

So now you simply execute the different commands to go through the lines of the script/function to see how it jumps through the if conditions, etc. If you want to execute the same command multiple times, you simply press Enter without feeding a new command.

You can at any point execute another Ex command if needed (see :help 'ex-command-index'), but note that you don't have direct access to the variables etc., in the debugger, unless they are global.

Sometimes, the place you want to get to is many lines into the code, and you really don't want to step all the way through the code until you get to this place.

In that case, you can insert a breakpoint at the exact line where you want to start the real debugging, and then just execute a cont as first command. A breakpoint is inserted by one of the following commands, depending on how you want it inserted:

  breakadd func linenum functionname
  breakadd file  linenum filename
  breakadd here

The first example sets a breakpoint on a particular function. The functionname can be a pattern like Myfunction* if you, for instance, want to break on any function with a name that begins with Myfunction. Sometimes, however, it is not in a function that the problem resides, but rather around a specific line in a file. If this is the case, then you should use the second command, where you give it a line number and a file name pattern as arguments to tell it where to break. The final command is used if you have already stepped to the right place in the file but want to be able to break on it the next time you go through the code in the debugger. This command simply sets a breakpoint on the current line, in the current file, where you currently are in the debugger. You can at any point of time get a list of breakpoints with the following command:

 :breaklist

If a breakpoint is no longer needed, you have to delete it. As when adding breakpoints, there are also few different ways to delete them. The simplest way to do it is by simply finding the number of the breakpoint in the list of breakpoints, and then using the following command:

 :breakdel number

Alternatively, you can delete the breakpoints the same way as you added them except that you now use breakdel instead of breakadd:

  :breakdel func linenum functionname
  :breakdel file linenum file

breakdel here If you want to remove all breakpoints, you can do it in one step by using this command:

:breakdel *

You can add a breakpoint directly on the command line when going into debug mode. Simply use the -c argument like: vim -D -c 'breakadd file 15 */.vimrc' somefile.txt