Ctags and Taglist: Convert Vim Editor to Beautiful Source Code Browser for Any Programming Language

This article is part of the on-going
Vi / Vim Tips and Tricks series. As a programmer or system administrator, you will be constantly browsing source codes and shell scripts.

Following are some typical activities that you may perform while browsing a source code file:

Navigating to the function definition by specifying the function name.
Navigating to the function definition from ‘function call’.
Returning back again to function call from the definition.
Viewing the prototype/signature of functions or variables.
Viewing the number of functions in a file, etc.,

In this article, let us review how to perform the above activities efficiently in
Vim editor using ctags and
taglist plugin.

The techniques mentioned in this article using Vim editor can be used for any programming language.

I. Ctags Package Install and Configure

Step 1: Installing ctags Package

# apt-get install exuberant-ctags

(or)

# rpm -ivh ctags-5.5.4-1.i386.rpm
warning: ctags-5.5.4-1.i386.rpm: V3 DSA signature: NOKEY, key ID db42a60e
Preparing...          ########################################### [100%]
1:ctags            ########################################### [100%]

Step 2: Generating ctags on your source code

Go to the directory where your source code is located. In the example below, I have stored all my C programming source code under ~/src directory.

# cd ~/src

# ctags *.c

The ctags command will create a filename tags the will contain all required information (tags) about the *.c program files. Following is partial output of the tags entries in the ctags file.

# cat tags
AddAcl  dumputils.c     /^AddAcl(PQExpBuffer aclbuf, const char *keyword)$/;"   f       file:
ArchiveEntry    pg_backup_archiver.c    /^ArchiveEntry(Archive *AHX,$/;"        f
AssignDumpId    common.c        /^AssignDumpId(DumpableObject *dobj)$/;"        f

II. 4 Powerful Ctags Usages inside Vim Editor

1. Navigate to function definition by specifying the function name using :ta

In the example below, :ta main will take you to the main function definition inside the mycprogram.c

# vim mycprogram.c
:ta main

By using this facility you can navigate to any function definition by specifying the function name.

2. Navigating to the function definition from ‘function call’ using Ctrl + ]

When the cursor is under the function call, then press CTRL + ] to go to the function definition. In the following example, when the cursor is in the function call ssh_xcalloc, pressing Ctrl + ] will take you to the ssh_xcalloc function definition.

# vim mycprogram.c
av = ssh_xcalloc(argc, sizeof(char *));

Note: If the ctags couldn’t find that function, you’ll get the following message in the vim status bar at the bottom: E426 tag not found ssh_xcalloc

3. Returning back again to function call from the definition using Ctrl + t

Press CTRL + t which will take back to the function call again.

4. Navigating through a list of function names which has the similar names

In this example, :ta will go to the function definition whose name starts with get, and also builds a list to navigate with the relevant functions.

# vim mycprogram.c

:ta /^get

Following vim commands can be used to navigate through relevant functions

:ts – shows the list.
:tn – goes to the next tag in that list.
:tp - goes to the previous tag in that list.
:tf – goes to the function which is in the first of the list.
:tl – goes to the function which is in the last of the list.

III. Taglist Plugin: Vim Editor as Ultimate Source Code Browser

The above Ctags might have not given a source code browsing feeling, as it is driven by commands instead of visually browsing the code. So if you want to navigate through the source as like navigating in the file browser, you need to use vim taglist plugin
which makes vim as a source code browser.

Author of the vim taglist plugin Yegappan Lakshmanan, says about it as

The “Tag List” plugin is a source code browser plugin for Vim and provides an overview of the structure of source code files and allows you to efficiently browse through source code files for different programming languages.

Step 1: Download the Vim Taglist plugin

Download it from from
vim.org website as shown below.

$ cd /usr/src

$ wget -O taglist.zip http://www.vim.org/scripts/download_script.php?src_id=7701[/code] 


Step 2: Install the TagList Vim Plugin
$ mkdir ~/.vim # if the directory does not exist already

$ cd ~/.vim

$ unzip /usr/src/taglist.zip
Archive:  /usr/src/taglist.zip
inflating: plugin/taglist.vim
inflating: doc/taglist.txt

Step 3: Enable the plugin in the ~/.vimrc
Add the following line to the ~/.vimrc to enable the plugin for Vim editor.

$ vim ~/.vimrc
filetype plugin on



Pre-Requisite: ctags should be installed to use taglist plugin. But it is not a must to generate the tag list manually by ctags command for using taglist plugin.

IV. 5 Powerful Features of Taglist Vim Plugin
1. Open the Tag List Window in Vim using :TlistOpen
# vim mycprogram.c
:TlistOpen



From the vim editor, execute :TlistOpen as shown above, which opens the tag list window with the tags of the current file as shown in the figure below.





Fig: Vim – Source Code Tag/Function List Windows
2. Jump to the Function Definition inside a source code
By clicking on the function name in the left panel, you would be able to go to the definition of the function as shown in the Figure below.





Fig: Jump to a function definition quickly


Apart form jumping to the function names quickly, you can jump to classes, structures, variables, etc., by clicking on the corresponding values from the tag-browser in the left hand side.

3. Jump to the function definition which is in another source file
When you are going through a function in a source file and would want to go to the function definition which is in another file, you can do this in two different methods.

Method 1:
If you had the ctags generated for that file, when the cursor is in the function call pressing CTRL + ] will take you to the function definition. And automatically the tag list window will show the tags for that newly opened file.

Method 2:
Open another file also in the same vim session which will update the tag list window with the information about that file. Search for that function name in the tag list window, and by pressing <CR> on that function name in the tag list window you can go
to the function definition.

4. Viewing the prototype/signature of functions or variables.
Press ‘space’ in the function name or in the variable name in the tag list window to show the prototype (function signature) of it in the VIM status bar as shown below. In the example below, click on selectDumpableTable function from the Tag-window and press
space-bar, which displays the function signature for selectDumptableTable function in the bottom Vim Status bar.



Fig: Display Function signature at the Vim Status Bar
5. Viewing the total number of functions or variables in a source code file
press ‘space’ in the tag type in the tag list window, which shows the count of it. In the example below, when the cursor is at ‘function’ press space, which will display the total number of functions in the current source code.



Fig: Display the total number of functions available in the source code


For effectively writing new source code files using Vim, please refer to our earlier articles:

Make Vim as Your Perl IDE Using perl-support.vim Plugin
Make Vim as Your C/C++ IDE Using c.vim Plugin
Make Vim as Your Bash-IDE Using bash-support Plugin.



Recommended Reading


Vim
101 Hacks, by Ramesh Natarajan. I’m a command-line junkie. So, naturally I’m a huge fan of Vi and Vim editors. Several years back, when I wrote lot of C code on Linux, I used to read all available Vim editor tips and tricks. Based on my Vim editor
experience, I’ve written Vim 101 Hacks eBook that contains 101 practical examples on various advanced Vim features that will make you fast and productive in the Vim editor. Even if you’ve been using Vi and Vim Editors for several years and have not read this
book, please do yourself a favor and read this book. You’ll be amazed with the capabilities of Vim editor.

Awesome Vim Editor Articles
Following are few awesome Vi / Vim editor tutorials that you might find helpful.

12 Powerful Find and Replace Examples for Vim Editor
Vi and Vim Macro Tutorial: How To Record and Play
Turbocharge Firefox Browser With Vim Editor Functionality Using Vimperator Add-on

Note: Please
subscribe to The Geek Stuff and don’t miss any future Vi and Vim editor tips and tricks.