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 ]

Ovid (2709)

Ovid
  (email not shown publicly)
http://publius-ovidius.livejournal.com/
AOL IM: ovidperl (Add Buddy, Send Message)

Stuff with the Perl Foundation. A couple of patches in the Perl core. A few CPAN modules. That about sums it up.

Journal of Ovid (2709)

Wednesday December 17, 2008
11:29 AM

Vim Filters: Documenting Exceptions

[ #38110 ]

Except in a couple of odd cases, our exceptions are spelled out explicitly in our code:

defined $arg_for->{foo}
  or X::Method::Argument::Missing->throw(...);

This means that it's trivial to find these exceptions with a regex, but not so trivial to find them in our docs since our docs usually don't list them.

Until now.

I wrote the following filter:

#!/usr/bin/env perl

use strict;
use warnings;
use List::MoreUtils 'uniq';

my $code = do { local $/; <STDIN> };
my @exceptions = uniq sort ($code =~ /(X::[^-]+)->throw/g);
my $exceptions = join "\n        " => @exceptions;
print "\nThrows: $exceptions\n$code";

And then typed mapped this to a visual area:

vnoremap ,e :!./add_exceptions.pl <cr>

And then I select the following bit of code (right before the =cut):

Pretend this is documentation ...

=cut

sub xml_diff {
    my ( $self, $old, $new ) = @_;

    return unless $old or $new;
    if ( $old and $new ) {
        unless ( $old->hasAttribute('href') and $new->hasAttribute('href') ) {
            X::Internal::XMLDiff::MissingHrefs->throw(
                old_xml => $old->serialize(1), new_xml => $new->serialize(1),
            );
        }

        unless ( $old->getAttribute('href') eq $new->getAttribute('href') ) {
            X::Internal::XMLDiff::DifferentHrefs->throw(
                old_xml => $old->serialize(1), new_xml => $new->serialize(1),
            );
        }
        if ($old->hasAttribute('revision') && $new->hasAttribute('revision')) {
            my $old_revision = $old->getAttribute('revision');
            if ($old_revision eq $new->getAttribute('revision')) {
                X::Internal::XMLDiff::IdenticalRevisions->throw(
                    revision => $old_revision,
                );
            }
        }
    }
    # more code
}

And then when I type ,e, I get the following text inserted right before =cut

Throws: X::Internal::XMLDiff::DifferentHrefs
        X::Internal::XMLDiff::IdenticalRevisions
        X::Internal::XMLDiff::MissingHrefs

About ten minutes later, I've now added this documentation to tons of modules. Vim filters rock.

Update: I screwed up. jplindstrom pointed out that the final line of the filter should look like this:

print "\nThrows:\n\n        $exceptions\n$code";

That makes the pod look like this, making it render correctly in HTML:

Throws:

        X::Internal::XMLDiff::DifferentHrefs
        X::Internal::XMLDiff::IdenticalRevisions
        X::Internal::XMLDiff::MissingHrefs

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.