Mike Friedman

I've been working on Redis::Client for a while now. It's not ready for production use yet, and there's a lot of work yet to be done, but it's much better than anything else on CPAN right now for talking to Redis.

I hate boilerplate with a burning passion, and I will often go to extreme lengths to avoid typing it. (I typed it once already, dammit! Leave me alone!)

After having a great time learning to mess with Dist::Zilla, I decided to give another of Ricardo's projects, Pod::Weaver a try. Here's the cool stuff I was able to do after not a lot of work.

It's pretty easy to set up your weaver.ini to control how Pod::Weaver does its thing. Like Dist::Zilla, Pod::Weaver has a bunch of PluginBundles to control its behavior according to your specification. The default bundle gives you a weaver.ini equivalent to this:

The interesting bit is [Collect / METHODS]. That will find all the POD-like commands called =method in your document, collect the block of text under each, and put them together under a =head1 METHODS section.

So this:

=method foobar

Here is some text

=cut

Becomes this:

=head1 METHODS

=head2 foobar

Here is some text

=cut

That's pretty spiffy, but I wanted to go further. Because Redis::Client has something like 120 methods (each one implements one Redis command) I wanted to organize them under different sections. So I copied-and-pasted the default config into my weaver.ini and modified it thusly:

The command lines specify the POD-like command to collect into each section. Now, I can use =string_method or =list_method or whatever, and the sections will automatically be collected under the appropriate =head1 section when Weaver runs.

But wait, there's more!

Another thing I wanted to do was link each method section to the Redis documentation for that command. It would be really tedious to type L<Redis FOO command|http://example.com/foo> over and over again, so I figured there must be a way for Pod::Weaver to do this. Like Dist::Zilla, it has a very extensible plugin architecture. Also like Dist::Zilla, the docs are somewhat lacking, and I had to dive through a lot of code to figure out what was going on.

I have no idea if the following constitutes "correct" usage of the Pod::Weaver API; I accomplished it mostly through trial-and-error and lots of Dumpering. But it works.

The result is that a link like Redis LREM Command gets automatically added to a section that begins =list_method lrem. Very cool!

To use this, I just had to add [-RedisLinks] to my weaver.ini. I'm not sure why the - is required (they're not for Dist::Zilla plugins), but it seems to explode if I omit it.

The plugin is not really useful for anything outside this specific project, but lacking anywhere else to put it, I just stuck it in the Redis-Client distribution, in case someone might find it useful as a reference.

And finally, since this distribution uses Dist::Zilla, to get all this stuff to happen automatically, I just add [PodWeaver] to dist.ini. Voila!