######################################################################
    CPAN::Unwind 0.03
######################################################################

NAME
    CPAN::Unwind - Recursively determines dependencies of CPAN modules

SYNOPSIS
        use CPAN::Unwind;
    
        my $agent = CPAN::Unwind->new();
    
        my $resp = $agent->lookup("Log::Log4perl");
        die $resp->message() unless $resp->is_success();
    
        my $deps = $resp->dependent_versions();
    
        for my $module (keys %$deps) {
            printf "%30s: %s\n", $module, $deps->{$module};
        }
            # Prints:
            #
            #  Test::Harness: 2.03
            #     Test::More: 0.45
            #     File::Spec: 0.82
            # File::Basename: 0
            #           Carp: 0

        print "Installation schedule:\n";
        for($resp->schedule()) {
            print "$_\n";
        }
            # Installation schedule:
            # Carp
            # File::Basename
            # File::Spec
            # Test::Harness
            # Test::More
            # Log::Log4perl

DESCRIPTION
    CPAN::Unwind recursively determines dependencies of CPAN modules. It
    fetches distribution tarballs from CPAN, unpacks them, and runs
    Module::Depends::Intrusive on them.

    SECURITY NOTE: CPAN::Unwind runs all Makefile.PL files (via
    "Module::Depends::Intrusive") of modules it finds dependencies on. If
    you are concerned that any module in the dependency tree on CPAN isn't
    trustworthy, don't use it.

  METHODS
    CPAN::Unwind supports the following methods:

    "my $agent = CPAN::Unwind->new();"
        Create a new dependency agent. The following options are supported:

        "cache"
            Provide your own "Cache::Cache" object (see Caching).

        "add"
            Provide additional dependencies that should be part of the
            result:

                CPAN::Unwind->new(add => 
                    ["Foo", "Bar" => 0.17,
                     ...
                    ]);

            indicates that "Foo" has a dependency on "Bar" 0.17, even if
            it's not listed in "Foo"'s "Makefile.PL". This way, you can fix
            broken Makefile.PL files of some CPAN modules, not listing their
            dependencies correctly.

    "$resp = $agent->lookup_single($module_name)"
        Goes to CPAN and fetches the tarball containing the module specified
        in $module_name. After unpacking the tarball, it will use
        Module::Depends::Intrusive to determine the modules it depends on.

        Returns a "CPAN::Unwind::Response" object.

    "$resp = $agent->lookup($module_name)"
        Calls "lookup_single" on $module_name recursively, builds a
        dependency tree and returns a "CPAN::Unwind::Response" object
        containing a consolidated dependency tree.

    CPAN::Unwind::Response supports the following methods:

    "$resp->is_success()"
        Returns true if there's a valid response and no error occurred.

    "$resp->message()"
        Returns a response's error message in case "is_success()" returned a
        false value.

    "$resp->dependent_versions()"
        Returns a ref to a hash, containing a mapping between names of
        dependent modules and their version numbers:

            { "Test::More"  =>  0.51,
              "List::Utils" =>  0.38,
              ...
            }

    "$resp->missing()"
        Similar to "dependent_versions()", but only modules that are
        currently *not* installed are returned.

    "$resp->dependents()"
        Returns a ref to a hash, mapping module names to their dependencies.

            { "Net::Amazon"  =>  ["Log::Log4perl", "XML::Simple"],
              "List::Utils"  =>  [],
              ...
            }

        If an entry holds a ref to an empty array, the module doesn't have
        any dependencies.

    "$resp->schedule()"
        Returns an installation schedule, a list of module names in the
        correct order without dependency conflicts. Returns "undef" if no
        schedule can be made due to circular dependencies.

  Caching
    To avoid costly downloads, "CPAN::Unwind" will cache dependencies in a
    Cache::FileCache cache, where they are stored indefinitely. Running it
    the second time on a module will speed up processing significantly.

  Turnkey Scripts
    "CPAN::Unwind" comes with a ready-to-use script "cpan-unwind", which
    gets installed in perl's bin path. It is ready to use, just call

        $ cpan-unwind Log::Log4perl

    to see which modules "Log::Log4perl" depends on.

    "CPAN::Unwind" requires a valid CPAN configuration.

EXAMPLES
        $ cpan-unwind Net::Amazon
        Carp Compress::Zlib Data::Dumper Fcntl File::Basename File::Path 
        File::Spec HTML::Tagset IO::Socket MIME::Base64 Socket Test::Harness 
        Test::More Test::Simple Time::HiRes URI XML::NamespaceSupport 
        Digest::base File::Temp HTML::Parser Log::Log4perl Net::FTP 
        XML::SAX XML::Simple Digest::MD5 LWP::UserAgent Net::Amazon

LEGALESE
    Copyright 2005 by Mike Schilli, all rights reserved. This program is
    free software, you can redistribute it and/or modify it under the same
    terms as Perl itself.

AUTHOR
    2005, Mike Schilli <cpan@perlmeister.com>