I'm a huge fan of Markdown. There's something elegant in using textual sigils to provide contextual information. I've used it for taking notes, creating RSS feed content, producing my blog, and even in emails (I soooo wish there were a way to convert markdown within Outlook for the web and GMail!)

So it should come as no surprise that I use a variety of tools to help me when writing markdown in (n)vim.

Because I've spent most of my professional life coding, I've also spent a lot of time using source control. I've been using specifically git for many years (even pre-dating the Zend Framework migration from Subversion). While I typically use a terminal multiplexer (for me, that's tmux; for others, that might be screen), and can move to another pane or create one quickly in order to run source control commands, doing so interrupts flow.

That's where vim-fugitive comes into play.

I've used vim and variants since 2001. In 2019, a friend introduced me to coc.nvim, which turned out to be my initial gateway to nvim, which I adopted a year or two later.

Yesterday, I discussed vim-surround. Today I'm going to discuss another plugin I've used a ton: tabular.

I've blogged about vim a number of times. I've been using vim or its descendents for 22 years now; I switched to neovim a few years back, but it's compatible with the existing vim ecosystem. (The primary differences, to my mind, are that it has a more optimized engine which is more performant, and that you can now configure and extend it using Lua if you want. Otherwise... it's just vim.)

I used to "collect" plugins, but at this point, particularly since switching over to neovim, I've reduced my plugins quite a bit, to only those I use on a regular basis.

So, I figured today, I'd start a mini-series as part of my Advent 2023 blogging, on some of my most used plugins.

Today's plugin: vim-surround.

In years past, folks across a variety of programming languages have organized Advent events in December, to highlight different tools, different frameworks, different programming practices, and more, often inviting guests to author each post.

I thought I'd try an experiment: I've had a ton of ideas for blog posts, many of them short, and just... never write them. What if I were to do a personal advent, and write these up?

Let's see how far I get.

Today's topic: Logseq.

I've been using Vim for close to a decade. I've often said that "Unix is my IDE" — because Vim is built in the Unix philosophy, allowing me to pipe input into it, out of it, and every which way I want. It fits very nicely with the Unix philosophy of doing one task well, and allowing redirection. I've found it ideal for web development in general and PHP development specifically — in fact, I've had excellent experiences in every language I've tried my hand at developing in when using Vim.

Vim is also my chosen productivity suite. When I want to write a document, I don't go into OO.o Writer or MS Word or some other word processor; I open up a window and start typing. In most cases, I can either cut and paste my work into other tools, or pipe it to transformation tools. I worry about the content first, and the presentation later… like any good MVC application. ;-)

Like any good tool, you have to invest time in it in order to reap its benefits. My learning has, to date, fallen into three time periods:

• The initial months in which I first learned Vim, via vimtutor and Steve Oualline's Vim book.
• A period in 2006-2007 when I felt the need to make my coding more efficient, and first started playing with exuberant-ctags and omni-completion.
• The last quarter of 2010 (yes, that's now) when I was introduced to a number of new tools via Twitter.

So, this is my Vim Toolbox, 2010 edition.

Chris Hartjes today was on a quest for a "find in project" feature for Vim. "Find in Project" was a feature of Textmate that he'd grown accustomed to and was having trouble finding an equivalent for.

The funny thing is that Textmate is a newcomer, and, of course, vim has had such a feature for years. The thing to remember with vim, of course, is its unix roots; typically if you know the unix command for doing something, you can find what you need in vim. In this case, the key is the vimgrep plugin, which ships in the standard vim distribution.

I use Vim for all my editing needs — TODO lists, email, presentation outlines, coding in any language… everything. So, I thought I'd start sharing some of my vim habits and tools with others, particularly those that pertain to using Vim with PHP.

One reason I've heard PHP developers use for adopting an IDE when developing is the ability to click on a class or function name and jump to the declaration. Sounds like magic, and it's definitely something I've desired.

One way I get around it is by adopting PEAR coding standards for naming my classes. Since they define a one-to-one mapping of class name to the file system (substitute the underscore character (_) with the directory separator), I can usually very quickly and easily open a class file, particularly if I start in the base directory of the project install.

Today, however, I found exuberant ctags, a library which can be used to generate an index file mapping language objects to source files and the line in the source file where they are declared. Contrary to its name, it's not just for the C language; it currently supports 33 different programming languages, including PHP.

I decided to try it out on the Zend Framework core library today. At first run, it was pretty useful. However, it was only mapping classes, and, in addition, only those defined with the single word 'class' — abstract classes and interfaces were entirely left out. So, I looked into the documentation to see if I could change the behaviour.

And, being a Unix program, of course I could. First off, you can add functions to the items it indexes with a simple flag. Additionally, you can use POSIX regular expressions to refine what it searches.

I whipped up the following script to create my tags index:

###!/bin/bash
cd /path/to/framework/library
exec ctags-exuberant -f ~/.vim/mytags/framework \
-h \".php\" -R \
--exclude=\"\.svn\" \
--totals=yes \
--tag-relative=yes \
--PHP-kinds=+cf \
--regex-PHP='/abstract class ([^ ]*)/
/c/' \
--regex-PHP='/interface ([^ ]*)/
/c/' \
--regex-PHP='/(public |static |abstract |protected |private )+function ([^ (]*)//f/'

This script creates the tag index in the file $HOME/.vim/mytags/framework. It scans for PHP files recursively through the tree, excluding any files found in a .svn directory (I'm using a checkout from the subversion repository). The file paths in the index are created relative to the tags file; this was important, because if this wasn't provided, vim was unable to jump to the file, as it couldn't find it. --PHP-kinds=+cf tells it to index classes and functions. Next, I've got three regular expressions. The first tells it to match classes beginning with 'abstract class' as classes. The second tells it to match interfaces as classes. The last is so that PHP 5 methods, which begin with a visibility operator, to be matched as functions.

Once the index file is generated (it takes less than a second), all you need to do in vim is tell it to load it: :set tags=~/.vim/mytags/framework. At this point, you can do all sorts of fun stuff. Place the cursor on a class name or method name, anywhere in it, and hit Ctrl-], and you'll jump to the file and line of its declaration; Ctrl-T then takes you back. If you change the invocation to Ctrl-W ], it will split the current window and open the declaration in the new pane. (If you're familiar with how help works with Vim, this should seem pretty familiar.)

One more reason to stick with Vim for your PHP editing needs. :-)