Lone Wolves

Thanks to the taglist vim plugin, vim users have access to a decent tag browser. A tag browser allows you to view a list of all variables, functions and classes and quickly jump to their definitions. Taglist is built on exuberant ctags so it support a large amount of languages. Unfortunately however, when the exuberant ctags people replaced their old PHP lexer with a brand new regexp-based parser the quality of parsing PHP code decreased dramatically. Ctags suddenly could not distinguish real class and function declarations from mere mentions of the words “class” and “function” in multi-line comments. This is because the ctags regular expression parses is inherently line oriented.

In this article I have two patches that greatly improve PHP support in exuberant-ctags. I will also show you how you can apply these patches on a Debian-based system.

Update 2009-07-07: David Mudrak has written an updated patch for Gentoo. I have ported his improvements back to my patch here. It fixed a problem with old-style functions without a visibility declaration and it applied the same trick to interfaces as well.

Properly handle multi-line comments

The exuberant ctags regular expression parser works on a line-by-line basis. The problem with this is that it cannot detect the start and end of a multi-line comment. Any text in the comment that contains the word “class” or “function” will make ctags think that it is a declaration instead of simply a comment.

Short of writing a full PHP lexer this cannot be easily fixed, but the patch below works around it by making a few assumptions. Almost all people write PHP code in such a way that a function or class declaration starts at a new line. Most people use docblock-style multi-line comments in their code. By simply looking at what is in front of a “class” or “function” you can predict with 99% certainty if it is a declaration or not. There should be only whitespace or keywords such as “public”, “static” or “abstract” in front of a class or function statement.

Download php-multiline-comment-v2.patch

I have already submitted this patch to the upstream exuberant-ctags project.

Only show class member variables

With the above patch ctags will correctly tag functions and classes, but variables are still not handled the way I like. The standard implementation tags all variables, including temporary variables and local variables. I prefer that ctags only tags class variables. Approximately the same logic as above is followed. A variable is a class variable if it is preceded by a keyword such as var, static, public, etcetera.

Download php-member-variables-only-v2.patch

Patching exuberant-ctags on Debian

On Debian and derivative it is quite easy to build your own custom packages. Lets start off by installing everything we need to build exuberant-ctags ourselves.

Next we create a working directory and download the source package.

I am assuming that you have downloaded the two patch files to your desktop. Apply them like this.

Now you need to increase the version number of the package so that you can later install it. You can use the dch to do this. It will read the changelog, add your name to it and open your preferred editor to edit the changelog.

I edited my changelog to look like this. Notice the “+multiline” that I added to the version number at the top.

Now we can build the package. The -b flag tells debuild that we only want to build a binary package. The -i flag runs some extra checks after building. The -us and -uc tell debuild that you do not wish to sign the package with your GPG key.

Exuberant-ctags should build without errors. Now you can install the package.

The last thing to do is to tell your package manager that you want to keep exuberant-ctags at the version you just installed and not install an updated version.

And that’s it! Now you should have much better support for taglist in vim with PHP. See the screenshot below for an example. Notice how there is no function called “in” and a variable called “$foo” in the laglist.