Falling in love with Pod::Weaver
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!)
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.
Here is some text
Here is some text
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:
command lines specify the POD-like command to collect into each section. Now, I can use
=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