Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

rjbs (4671)

rjbs
  (email not shown publicly)
http://rjbs.manxome.org/
AOL IM: RicardoJBSignes (Add Buddy, Send Message)
Yahoo! ID: RicardoSignes (Add User, Send Message)

I'm a Perl coder living in Bethlehem, PA and working Philadelphia. I'm a philosopher and theologan by training, but I was shocked to learn upon my graduation that these skills don't have many associated careers. Now I write code.

Journal of rjbs (4671)

Saturday June 07, 2008
11:08 AM

new distribution: pod-eventual

[ #36611 ]

I've been wanting to do some mucking around with POD. I started a little down this route a few weeks ago with Pod::Coverage::TrustPod, and what I found was that it was really a pain in the butt to easily say, "this file contains POD. Give me the content of hunks between =begin foo and =end foo. I'm sure it's possible, and that if you understand Pod::Simple you can do it fairly quickly, but I just got too confused and side-tracked trying to figure it out. I really just wanted to get a hunk of data by saying something like:

my @hunks = Pod::Imaginary->parse('file.pm')->for_formatter('foo');

Later, this sort of thing started to bite me again, because Pod::Simple seems much more geared to... well, to getting things right. I mean, it doesn't want you to make up directives all over the place, it understands the relationship between over and item, and it cares about what's inside of text paragraphs (like C<> and all that).

After talking about it with Dieter for a while and growing more grumpy, I realized that this was just like the INI parsing situation. POD is just a line oriented data format. I could just write a little state machine to collect POD events and do whatever I wanted.

So, Wednesday after ABE.pm, I wrote Pod::Eventual. It reads POD and collects lines into events, which look something like these:

my @events = (
  { type => 'command', command => 'head1', content => "NAME\n" },
  { type => 'text',    content => "Pod::Eventual - read POD as events\n" },
);

Sure, it doesn't realize that most people would consider that text paragraph to be "part of" the header. That's fine! It means it also doesn't need to be special cased the other way to handle this:

=for HTML
<hr />

...and now some text!

In that case, the paragraph is definitely not part of the for construct.

Pod::Simple works something like this, under the hood, but it's much more complicated. Pod::Eventual ignores the structure of the document beyond paragraphs, and it doesn't look at the content of the text paragraphs. It also might just get some cases wrong. (Failing tests welcome!)

Still, it makes it very easy to write quick (but accurate) POD handling code.

My hunk-finder from above could probably be:

my @hunks = grep {
  $_->{content} =~ /^foo$/m
  and ($_->{command} =~ 'begin' .. $_->{command} =~ 'end')
} Pod::Eventual->read_file('file.pm');

...or something very like it.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.