Hacking Thy Fearful Symmetry

Contributing to CPAN: PAUSE Id, Bug Tracking, and Code Repositories

2010-02-06T18:04:33Z

originally published on the Pythian blog.

Want to contribute to your favorite CPAN module, or maybe create your own, but don't have the foggiest idea how to do it? Here are a few notes, tips, tricks, and links that might help you get started.

PAUSE id

While bringing awesome street cred, having a PAUSE id is strictly necessary only if you want to maintain or co-maintain a module. If you just want to contribute code, you'll perfectly be able to do without, as it will usually be done via patches submitted to a bug tracking system, a code repository or using good ol' email.

Becoming a co-maintainer

Becoming the co-maintainer of a module gives you the power to upload authorized releases of the modules on CPAN. To become one, the maintainer of the module simply has to promote you as such on PAUSE.

Creating a new module

You want to create your own module? Excellent! But before you do it, make sure that you

verified on CPAN that there's not already a module that already scratch that particular itch.
made sure that the module uses a descriptive and pertinent namespace.

Once this is done, go ahead: log on PAUSE and register the module.

Adopting an abandoned module

There's a module apparently abandoned by its owner that you'd love to take over? The procedure for that is given in the CPAN FAQ, and it can be boiled down to:

Try to get in contact with the current maintainer.
If you reach him or her, make puppy eyes and ask if you can take over.
If they are agreeable, they will flip over the maintenance of the module to you on PAUSE, and that's all there is to it.
If you tried their email addresses, poked around in mailing lists, forums and other places without any luck, wait a little bit (a couple of weeks) and contact the PAUSE admins.

Module created! How do I upload releases, now?

You upload new versions of a module via the PAUSE interface or via ftp.

Alternatively, and more conveniently, you can also use the cpan-upload script provided by CPAN::Uploader.

Bug Tracking

Contributing to a module means fixing bugs or implementing new enhancements. To find those, who are you gonna call? The Bug Tracker!

rt.cpan.org

By default, every module on CPAN has a bug tracking queue on rt.cpan.org. For example, the one for Git::CPAN::Patch is at http://rt.cpan.org/Public/Dist/Display.html?Name=Git-CPAN-Patch.

Bug reporting can be done via the web interface, or by sending an email to bug-module@rt.cpan.org (e.g., bug-git-cpan-patch@rt.cpan.org).

...or somewhere else

Sometimes, the module's maintainer uses a different bug tracking system. You'll typically find it mentioned in the POD, or in the META.yml:

$ curl -L http://search.cpan.org/dist/Git-CPAN-Patch/META.yml | \
  perl -MYAML -0 -E'say Load(<>)->{resources}{bugtracker}'

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-CPAN-Patch

If you don't feel inclined to dig into META.yml for information, there is a Greasemonkey script that will do it for you, and automatically add a link to the bugtracker (along some other goodies) on the module's CPAN page.

...or here, there and everywhere

What if the bugs are kept on rt.cpan.org, and on the local bug tracking system of Github, and a few other places? You can either follow them manually, or you can get funky and experiment with SD, a peer-to-peer ticket tracking system that can sync with and merge the information of several online bug tracking systems. SD, it goes without saying, can be found on CPAN as App::SD.

Code Repository

Most, but not all, modules have a public code repository somewhere out there. Just like for the bug tracking system look for it in the POD, or in the META.yml. It will be displayed on the module's cpan page as well.

$ curl -L http://search.cpan.org/dist/Git-CPAN-Patch/META.yml | \
    perl -MYAML -0 -E'say Load(<>)->{resources}{repository}'

git://github.com/yanick/git-cpan-patch.git

Na na na na, Na na na na, GitPAN!

Thanks to Schwern, all CPAN distributions now have a GitHub repository tracking its releases. They can all be found under the GitHub gitpan account, and follow the pattern http://github.com/gitpan/Git-CPAN-Patch.

Git::CPAN::Patch

Speaking of Git::CPAN::Patch, you can use its set of scripts to ease the creation of CPAN-related git repositories. It also includes scripts to send patches directly from your local repository to a rt bug queue.

Local POD browsing: using Pod::POM::Web via the CLI

2010-01-16T17:21:22Z

post originally published in the Pythian Blog

Edit: After I've written the original post, a colleage pointed me to a very similar entry in Perl Hacks. I just want to say that (a) no blatant plagiarism was intended and (b) I should read that book cover to cover one of these days. In any case, I'm keeping this post alive as it's using a different podserver and, more interestingly, the completion part of it brings a little extra sugar to the original hack.

Half the time I want to peek at the doc of a module, I hit perldoc. The rest of the time I type cpan Some::Module^[1] in Firefox and read the POD straight out of CPAN. And while it’s pretty and handy, it also feels kinda silly to go on a remote server to read documentation that is also sitting on my computer. Surely, I tell myself, there must be a better way.

Cue in the several Perl modules that act as local POD web servers. After giving a few of them a quick test-run, I decided to give Pod::POM::Web a try. Being a CLI jockey, I wanted to be able to open the POD of a module from the command line. Not a problem, I just had to create the script ‘pod’:

#!/bin/bash

POD_PORT=8787

perl -MPod::POM::Web \
   -e"Pod::POM::Web->server($POD_PORT)" 2> /dev/null &

PAGE=`perl -e's(::)(/)g for @ARGV; print @ARGV' $1`

HOSTNAME=`hostname`

kfmclient openURL "http://${HOSTNAME}:$POD_PORT/$PAGE";

There is not even a need to fire up the Pod::POM::Web server beforehand: the script will do it for us (if the server is already running, subsequent calls to pod will harmlessly try to start a new server on the same port and fail).

It should be noted that ‘kfmclient’ is KDE-specific — for any other desktop environment, you might want to change that to a direct call to firefox.

It’s already not too shabby, but wouldn’t it be even better with a little bit of auto-completeness magic? To do that, we need a short script, pod_complete:

#!/usr/bin/perl

use 5.010;

use List::MoreUtils qw/ uniq /;

my ( $sofar ) = reverse split ' ', $ENV{COMP_LINE};

$sofar =~ s(::)(/)g;

my ( $path, $file ) = $sofar =~ m!^(.*/)?(.*)?$!;

my @dirs = map { $_.'/'.$path } @INC;

my @candidates;

for ( @dirs ) {
    opendir my $dir, $_;
    push @candidates, grep { /^\Q$file/ } grep { !/^\.\.?$/ } readdir $dir;
}

if ( $path ) {
    $_ = $path.'/'.$_ for @candidates;
}

s/\.pm$// for @candidates;
s(/+)(/)g for @candidates;

say for uniq @candidates;

All that is left is to add . . .

complete -C pod_complete pod

. . . to our bashrc, and it should all work (with the caveat that the modules must be entered as Some/Module instead of Some::Module).

$ pod XML/XPath
XML/XPath        XML/XPathScript

[1] If you don’t already know the trick: create a bookmark with keyword ‘cpan’ and location http://search.cpan.org/search?query=%s.

Ottawa Perl Mongers presents: FormFu Assassin

2009-11-29T22:33:31Z

Once more, the Ottawa Perl Mongers assemble!

When: Thursday December 3^rd, 2009, at 7:00pm.

Where: at the Pythian headquarter

What: I'll be presenting how I'm implementing AJAX forms in a Catalyst application, using the deadly magic of Mason, Prototype and FormFu.

Bonus: Pizza will be graciously provided by Pythian. So if you plan on coming, please let me know so that I can be a good little ninja and make the number of slices match the number of attendees.

Perl Module Dependencies: how to require the latest, and nothing less

2009-10-14T23:27:35Z

entry originally published on the Pythian blog.

Recently, hanekomu was contemplating how to make subsequent installs of a Task::BeLike module upgrade its dependencies to their latest version.

The idea is intriguing. It’s not something you want to do for a typical module, but it makes sense in the context of Task::BeLike. If you care enough about a module to put it in your Task::BeLike, you probably care enough to want to upgrade when there’s a new version out there.

Alas, I think hanekomu’s proposed way of doing it is flawed (mind you, the debate is still going on as of the writing of this entry, and I can very well still be proven wrong). But after some pondeferous chin scratching, I might have come with a cunning alternative to it.

Let’s say that in your Build.PL (the logic would be the same for a Makefile.PL) you have your dependencies stashed in %dependencies. Something akin to:

%dependencies = (
    XML::LibXML      => 0,          # any version will do
    XML::XPathScript => '1.42',     # 1.42 or higher
    Moose            => 'latest',   # nothing but the shiniest!
);

All we want to do, really, is to switch the latest for, well, the latest version available. Surprisingly, that something that is almost as easy to do than to say:

for my $mod ( keys %dependencies ) {
    next unless $dependencies{$mod} eq 'latest';

    require CPANPLUS::Backend;
    state $cb = CPANPLUS::Backend->new;

    $dependencies{$mod} = $cb->module_tree( $mod )->package_version;
}

Yes, that’s really all there is to it. A little further hacking later, I have incorporated the functionality to my own Task::BeLike::YANICK module. The way I implemented it, installing the module the usual way will yield no surprise (i.e., dependencies already present are not going to be updated). But if the environment variable TASK_UPGRADE is set to true, like so:

TASK_UPGRADE=1 cpan -f Task::BeLike::YANICK

. . . then the magic is going to be unleashed (the -f is to force the re-install, if the Task has already been installed before).

Alternatively, just to know which dependencies are out-of-date, one can also extract the distribution and do a

perl ./Build.PL --upgrade
./Build prereq_report

The Joy of Finding Your Code in Unexpected Places

2009-10-08T23:21:16Z

entry originally published on the Pythian blog.

picture by Geophaps
Hey, that one in the sixth row…
Doesn’t he looks familiar?

So there I am, on my morning bus ride, reading my copy of The Definitive Guide to Catalyst (keep your eyes peeled for the upcoming review of the book in the Perl Review).

I’m near the end, in Chapter 11, Catalyst Cookbook. As it is with most tech books, the last chapters are the most engrossing, as the gloves finally come of and the writers throw at you all the wonderful, mind-bending stuff that the rest of the book prepares you for.

The section I’m at is about the development process. Specifically, it shows how you can put hooks in your versioning system to automatically screen commits to conform to Perl::Critic and Perl::Tidy policies. The given example script uses Git, which is just dandy with me as it is my current VCS of choice. But there’s something . . . funny about that script. The way the utility functions are stashed at the end after a

### utility functions ##############################

line. The choice of variable names. The comments. It all feels oddly familiar. And then my eyes fall on the line

exit 0 unless @dirty; # Alles gut

and everything falls into place. The script in the book is a wee bit different and has been improved upon, but its origin is unmistakable. Somehow, unexpectedly, a hack of mine found its way into publication. Fame, glory, and page 293 of the Catalyst book, I can finally claim ‘em all as rightfully mine!

But, serendipitous glee aside, three important lessons lie in this little story.

1. Blog posts, great and small, the Perl Gestalt, it reads them all

All clever tricks, code snippets, and insights you come up with? Blog ‘em. Even if you think they are only an itsy widdly little bit clever. Chances are, if there is a spark in there, it’ll ignite the mind of someone insaner than you are and ultimately result in something awe-inspiring. Or, more importantly, something awe-inspiring for which you’ll have bragging rights.

And don’t despair if your blog entries mostly go without comments. Provided that you are broadcast by an aggregator or two, people will read you. Silently, furtively, your thoughts will slip in the Perl subconscious like so many pumpkin seeds into autumn soil.

2. Code carries your DNA

No big discovery here, but it’s interesting to see how surprisingly easy it is to recognize one’s own code. One would think that nothing looks more like a line of code than another line of code, the same way nothing looks more like a baby emperor penguin than another one.

Yet, we do recognize ours by a curve of the beak, a specific timbre of the voice. Admittedly, Perl’s flexibility provides much more latitude for transposing our idiosyncrasies unto our digital babies. But then again, isn’t why a lot of us love Perl so much?

3. Some of my code made it into a Catalyst book!

I mean, seriously, how terminally cool is that?!

Gaining My Money Where My Mouth Is

2009-08-23T17:46:41Z

In the last three months, I've been eerily quiet both on my blog (it's been so long, I'm afraid I'm going to bolt straight past Paper Man and end up Pulp Man) and on the module front. Ironically enough, this long silence has actually been caused by events in my life that have Perl plastered all over them.

In a nutshell, after 11 years of working in the telecom industry, I've decided to take the plunge and try something different. As of the end of July, I've switched allegiance to The Pythian Group. They are a company specializing in database support, and they happen to use Perl-based internal tools. Which is where, as the astute reader may surmise, I enter the picture.

So, no more watching from the peanut gallery for li'll old me -- we'll now see if I can make a living out of that Perl stuff.

No need to say, I'm in equal part thrilled, exhilarated and terrified of what lies ahead. Hopefully, my new colleagues will feel the same way before long. :-)

Moose and Daemons, now on video!

2009-05-31T17:49:56Z

The talks of the last perl Monger meeting are now available online for your viewing pleasure. In addition of the classic decks of slides, thanks to Andrew Ross of the FOSSLC we also have full-fledged recordings of the talks:

Tim Procter's ''Portable Perl Daemons'': audio-visual extravaganza or just the slides.
Your truly introduction to Moose: audio-visual extravaganza or just the slides.

Enjoy!

Ottawa Mongers: Moose & Daemons

2009-05-23T15:24:10Z

The Ottawa Mongers meet this month!

On the program, we have a Monger special edition of the Moose talk I gave at the FOSSLC Summercamp last week, and Tim Procter of the Pythian Group will give a talk about Perl Daemon Processes.

Location and Time

The meeting will take place Tuesday May 26^th, at 7:00pm. We'll be at the Pythian Group office (Suite 1000, 116 Albert Street).

If you plan to come, please let me know so that we make sure we can accommodate everyone.

To 5.10 or not to 5.10

2009-05-18T01:27:04Z

Ever since Perl 5.10 came out, my soul is torn asunder by a particularly prickly dilemma.

On one hand, my love of shiny new toys urge me to go forth and use the new features of 5.10 to their full extent so that my code is clean, concise and, most important of all, spiffy.

On the other hand, my insatiable thirst for glory dictates that I should strive to make my modules accessible to the widest range of configurations possible. In that light, setting the requirement bar to Perl 5.10 is a severe drawback. Kinda like longing for world domination, but restricting oneself to invade only countries with names beginning with 'M'.

So far I pretty much went the 5.8-compatible way. But the call of the shiny is becoming just too strong, and from now on I'll try a new approach.

Conceptually, I'll divide my modules into two categories: modules that are for general consumption (WWW::Ohloh::API, XML::XPathScript, etc), and modules that are tools for developers (Dist::Release, Git::CPAN::Patching, Test::Pod::Snippets).
The formers, I'll keep 5.8-compatible. For the latter, though, I'll go on a limb and assume that they'll be used on development machines. Machines that can afford -- nay, should be expected -- to have a Perl 5.10 binary stashed somewhere.

Now, my only hope is that by doing so I'll not alienate my user base. Well, not exactly: I also hope there is actually a user base to alienate in the first place. :-)

Me, Moose and Summercamp 2009

2009-05-10T23:49:28Z

(by the by, I joined the fun and accepted the Perl Iron Man Challenge.)

As assiduous readers of my blog may recall, last year I gave a 35 minutes Perl introduction at OSBootCamp 8. For unphantomable reasons, I've been asked to come back and recidive for FOSSLC Summercamp 2009, which is happening on the 13, 14 and 15 of May.

This time, my talk is going to be an introduction to Moose. Why Moose? Since my goal is to hook unsuspecting students on Perl, I figured the easiest way to tip them to the dark side would be to show those java-tainted young minds the latest and shiniest OO coolness that the Perl community has to offer.

Sorry, what? ... Didn't I mention in a previous blog entry that I prefered Object::InsideOut over Moose?

Ah... Hum... Well, yes, true, I might have said that... (darn those assiduous readers)

Mind you, I still think that Object::InsideOut is a very fine module indeed, but several things made me progressively slide in the Moose camp:

Moose has an incredibly strong momentum in the community.
Notwithstanding the fact that when so many bright people get excited about something, it's usually for a good reason, it also means that Moose development is thriving. And not only core development, but extensions are by now abounding.
And this, for my little lazy heart, is true bliss. The MooseX namespace is quickly growing into a mini OO-CPAN.
At the time, I was arguing with Yuval that I had no need for those cute 'before' and 'after' method modifiers. Ah! That was before I seriously tried using them...
Roles. Those things are dangerously addictive. And they do such a damned good job of simplifying one's code.
MooseX::Method::Signatures, Moose types, coercion, and the myriad of other things that all work together to move the tedious bits of coding out of the way, and to fragment the good parts into small, easy to understand/maintain pieces.
Meta-programming. Pure mad scientist type of fun. How can I possibly resist?

So yeah, I call on my right to change my volatile mind. Color me a new Moose adept. And, hopefully, I'll similarly be able to color some more converts this Friday. Wish me luck.

Moose Attribute Meta Meddling

2009-05-02T04:47:55Z

This week I finally got a good excuse to go on and dabble with Moose meta-programming. In my WWW::Ohloh::API classes, a lot of attributes take their values from an initial xml snippet. The original, naive way those values were extracted was along the lines of:

has xml_src => (
    is   => 'ro',
    isa => 'XML::LibXML::Node',
);

has created_at => (
    is         => 'ro', 
    lazy      => 1,
    default => sub {
        return $_[0]->xml_src->findvalue( 'created_at' );
    }
)

has sender_account_name => (
    is          => 'ro', 
    lazy      => 1,
    default => sub {
        return $_[0]->xml_src->findvalue( 'sender_account_name' );
    }
);

Not harrowingly horrible, but rather repetitive. I figured out it would be much niftier to provide the name of the attribute holding the source xml and the pertinent xpath, and let Moose magic take care of the rest. Something like:

has created_at => (
    metaclass => 'XMLExtract',
    is => 'ro', 
    xml_src => 'xml_src',
    xpath => 'created_at',
)

Well, turns out that once one knows how, this is fairly easy to do:

package XMLExtract;

use Moose;

extends 'Moose::Meta::Attribute';

has 'xml_src' => ( isa => 'Str', );

has xpath => ( isa => 'Str', );

has '+lazy' => ( default => 1 );

before '_process_options' => sub {
    my ( $class, $name, $options ) = @_;

    die "attribute '$name' in class '$class' must be lazy-evaluated\n"
    if defined $options->{lazy} and not $options->{lazy};

    my $src = $options->{xml_src} ||= 'xml_src';
    my $xpath = $options->{xpath} ||= $name;

    $options->{default} = sub {
        return $_[0]->$src->findvalue($xpath);
    };

};

1;

If you notice, I've set 'xml_src' and 'xpath' to default to 'xml_src' and the name of the current attribute, so that the code can be further simplified to

has xml_src => (
    is   => 'ro',
    isa => 'XML::LibXML::Node',
);

has created_at => (
    metaclass => 'XMLExtract',
    is => 'ro', 
)

has sender_account_name => (
    metaclass => 'XMLExtract',
    is => 'ro', 
);

Short, sweet and to the point. Now we're talking code I like!

Ruhr.pm: Die Meister des Psycho-Lamas

2009-04-22T00:55:26Z

Last month, thanks to a concerted effort of German Perl Mongers[1] I was able to meet with the wonderful folks of Ruhr.pm.

It turns out that not only the Ruhr-area mongers are a superlatively friendly bunch, but they have pretty cool presentations too.

The feature presentation of the night was Fuse mit Perl, by Simon Wilper. After he was done, I also got treated with a quick replay of two previous presentations dealing with image manipulation. One was about openCV, a facial recognition software, and its Perl interface, and the other one was about the uses of Image::Magick, including the detailed instructions on how to create a psycho-llama. That last bit, I daresay, was worth the trip to Germany all by itself. The script to create the thing is in the presentation companion tarball, check it out (well, unless you suffer from epilepsy, in which case you want to stay as far away as possible).

So, bottom-line: Ruhr.pm rocks big time. If you're ever passing in the vicinity, I highly recommend paying them a visit. :-)

[1] Renée Bäcker saw my use.perl.org blog entry and forwarded the information to Ruhr.pm, Veit Wahlich -- fearless leader of the Ruhrgebiet mongers -- contacted me and arranged the details, and René Knopp was dispatched to pick me up from the train station. Many thanks to the whole bunch!

Just another Perl Ausländer

2009-03-04T19:24:15Z

Ever since I've learned about the existence of $foo - Perl Magazin, I've been awfully curious to take a peek at it. Unfortunately, they don't ship subscriptions internationally. So I went for the obvious workaround: I hunted high and low for the loveliest German lass I could find, asked her to marry me, and coaxed her family to get and forward me a subscription for the magazine as this year's Christmas gift. Worked like a charm.

And it was worth it too. The magazine is even better than I expected, and it's high praises to the authors that I learned quite a few things from the articles even though my German is still at a protozoic stage. Whether you're a German wanting to learn Perl, or a Perl hacker wanting to learn German, I heartily recommend it.

And talking of Germany, I'll embark tomorrow on a three-week vacation trip across the republic. If there are any Perl mongers meeting this month around Duisburg, Morsbach or Schwieberdigen who wouldn't mind having an Ausländer in their midst, please feel free to drop me an email. :-)

Académie des chasseurs de primes

2009-02-14T23:41:52Z

Next week is going to see the release of the comic book album 'Académie des chasseurs de primes' (art by Benoit Godbout, stories by Michel Lacombe and yours truly). If you are in Montréal, there's going to be a reception Wednesday that Ben and Michel will be attending (see attached image).

We have a movie teaser, and we'll soon have a working website as well.
The album itself will be sold in librairies in Québec and France. I'll see if there's a way to have an internet sale channel as well.

CPAN Patching with Git

2008-12-29T19:18:26Z

=pod A few months ago, brian posted a blog entry about L. In the ensuing discussion, I pointed at a possible way to automatise the process a step further by punting the generated patch to rt.cpan.org. The hack was well-received and, with (very) minimal coaxing, I was subsequently convinced to expand on the idea for the Perl Review. The resulting piece is now available in L. In the article, the initial command-line hack has morphed into four scripts -- C, C, C and C -- that pretty much take care of all the administrative overhead of module patching. In most cases, grabbing a distro, fixing a bug and sending the patch can be done in four lines: $ git cpan-init Some::Module $ git checkout -b mypatch ...hack hack hack... $ git rebase -i cpan $ git cpan-sendpatch And, no, the lack of hyphen between C and C isn't a typo; the article also covers how to seamlessly integrate the new scripts into the git infrastructure (as Edna Mode would say, I). Of course, I'm burning to say more, but I'll have to stop here. To know the whole story, you'll have to wait for The Perl Review to land in your mailbox (you are subscribed to TPR, I).