NAME

       Algorithm::Dependency::Weight - Calculate dependency 'weights'

SYNOPSIS

         # Create a source from a file
         my $Source = Algorithm::Dependency::Source->new( 'file.txt' );

         # Create a Weight algorithm object
         my $alg = Algorithm::Dependency::Weight->new( source => $Source );

         # Find the weight for a single item
         my $weight = $alg->weight('foo');
         print "The weight of 'foo' is $weight\n";

         # Or a group
         my $hash = $alg->weight_hash('foo', 'bar', 'baz');
         print "The weight of 'foo', 'bar', and 'bar' are $hash->{foo},"
             . " $hash->{bar} and $hash->{baz} respectively\n";

         # Or all of the items
         my $all = $alg->weight_all;
         print "The following is a list from heaviest to lightest:\n";
         foreach ( sort { $all->{$b} <=> $all->{$a} } keys %$all ) {
             print "$_: $all->{$_}\n";
         }

DESCRIPTION

       In dependency systems, it can often be very useful to calculate an aggregate or sum for
       one or all items. For example, to find the "naive install weight" of a Perl distribution
       (where "naive" means you treat each distribution equally), you would want the distribtion
       (1) + all its dependencies (n) + all their dependencies (n2) recursively downwards.

       If calculated using a normal Algorithm::Dependency object, the result would be (in a
       simple systems) equal to:

         # Create your normal (non-ordered alg:dep)
         my $dependency = Algorithm::Dependency->new( ... );

         # Find the naive weight for an item
         my $weight = scalar($dependency->schedule('itemname'));

       "Algorithm::Dependency::Weight" provides a way of doing this with a little more
       sophistication, and in a way that should work reasonable well across all the
       Algorithm::Dependency family.

       Please note that the this might be a little (or more than a little) slower than it could
       be for the limited case of generating weights for all of the items at once in a dependency
       system with no selected items and no circular dependencies. BUT you can at least rely on
       this class to do the job properly regardless of the particulars of the situation, which is
       probably more important.

   METHODS
   new @params
       The "new" constructor creates a new "Algorithm::Dependency::Weight" object. It takes a
       number of key/value pairs as parameters (although at the present time only one).

       source => $Source
           The "source" param is mostly the same as for Algorithm::Dependency.  The one addition
           is that as a source you can provide an Algorithm::Dependency object, and the
           Algorithm::Dependency::Source for that will be used.

       Returns a new "Algorithm::Dependency::Weight" object, or "undef" on error.

   source
       The "source" accessor returns the source used for the weight calculations.

       This will be either the one passed to the constructor, or the source from inside the
       "Algorithm::Dependency" object passed as the "source" param (not the object itself, its
       source).

   weight $name
       The "weight" method takes the name of a single item and calculates its weight based on the
       configuration of the "Algorithm::Dependency::Weight" object.

       Returns the weight as a scalar (which in the naive case will be an integer, but in more
       complex uses may be any real number), or "undef" on error.

   weight_merged @names
       The "weight_merged" method takes the name of a set of items and calculates an aggregated
       weight for the whole set.

       Returns the weight as a scalar, or "undef" on error.

   weight_hash @names
       The "weight_hash" method takes a list of item names, and calculates their weights.

       Returns a reference to a "HASH" with the item names as keys and weights as values, or
       "undef" on error.

   weight_all
       The "weight_all" method provides the one-shot method for getting the weights of all items
       at once. Please note that this does not do anything different or special, but is slightly
       faster than iterating yourself.

       Returns a reference to a "HASH" with the item names as keys and weights as values, or
       "undef" on error.

TO DO

       - Add support for non-naive weights via either custom code or method name

SUPPORT

       Bugs should be submitted via the CPAN bug tracker, located at

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Dependency>

       For general comments, contact the author.

AUTHOR

       Adam Kennedy <adamk@cpan.org>

SEE ALSO

       Algorithm::Dependency, Algorithm::Dependency::Source

COPYRIGHT

       Copyright 2003 - 2009 Adam Kennedy.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.