On Tue, Jan 27, 2009 at 4:07 PM, brian d foy wrote:
I'm doing a lot of work with the CPAN.pm programmer's interface for a
client, and I'm spending a lot of time in the source figuring out what
the rules are. As I go through this, I intend to expand the
documentation for those bits.
Awesome. You know that CPAN.pm migrated to github, right? So you can fork
from
http://github.com/andk/cpanpm/tree/master and hack away at
documentation.
I've been meaning to create lib/CPAN/API.pod anyway to start to consolidate
this kind of stuff. I just ran out of bandwidth. If there are bits I can
help with, please let me know (along with your timeframe) and I'll tell you
whether I can commit to it.
For install, what should install() return? Is it just true or false if
it worked or not? It looks like most errors end up returning nothing
(so undef on failure), but I think I'm also getting false in some cases
where things worked. I'm setting up some specific test cases to see if
I can deduce all of that. However, if I know what it should do, I can
document that too.
When I looked at this for a question on stackoverflow, I concluded that the
thing to do was check $mod->uptodate rather than rely on the return value of
install.
my $mod = CPAN::Shell->expand("Module", "Module::Name::Here");
if ( ! $mod->uptodate ) {
$mod->install;
die "Problems installing" unless $mod->uptodate;
}
As I recall, a lot of things return to shortcut control flow and those
aren't necessarily consistent in returning true/false. Depending on how
they are invoked, I think some of those values just fall through to the end
of install.
I'd prefer to see things either return true/false, but it may be that things
should return an object that can provide context. E.g. "tests passed, but
dependency was missing" -- is that success for "test Foo::Bar" or failure?
If running CPAN::Shell->test(*) then it's success, but when
CPAN::Shell->install calls test() then it's a failure. (That might be a
contrived example, so please don't nit pick me over it.) Many of the
functions in CPAN::Distribution do return CPAN::Distrostatus objects, but I
don't think that works for routines from Shell that might be called against
module names, not distribution names.
-- David