On Tue, Jan 27, 2009 at 4:07 PM, brian d foy <[email protected]> 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
