.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Algorithm::Dependency::Weight 3"
.TH Algorithm::Dependency::Weight 3 "2009-04-14" "perl v5.22.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Algorithm::Dependency::Weight \- Calculate dependency 'weights'
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # Create a source from a file
\&  my $Source = Algorithm::Dependency::Source\->new( \*(Aqfile.txt\*(Aq );
\&  
\&  # Create a Weight algorithm object
\&  my $alg = Algorithm::Dependency::Weight\->new( source => $Source );
\&  
\&  # Find the weight for a single item
\&  my $weight = $alg\->weight(\*(Aqfoo\*(Aq);
\&  print "The weight of \*(Aqfoo\*(Aq is $weight\en";
\&  
\&  # Or a group
\&  my $hash = $alg\->weight_hash(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq);
\&  print "The weight of \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, and \*(Aqbar\*(Aq are $hash\->{foo},"
\&      . " $hash\->{bar} and $hash\->{baz} respectively\en";
\&  
\&  # Or all of the items
\&  my $all = $alg\->weight_all;
\&  print "The following is a list from heaviest to lightest:\en";
\&  foreach ( sort { $all\->{$b} <=> $all\->{$a} } keys %$all ) {
\&      print "$_: $all\->{$_}\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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 \*(L"naive install weight\*(R" of a Perl distribution (where \*(L"naive\*(R"
means you treat each distribution equally), you would want the
distribtion (1) + all its dependencies (n) + all \fBtheir\fR
dependencies (n2) recursively downwards.
.PP
If calculated using a normal Algorithm::Dependency object, the
result would be (in a simple systems) equal to:
.PP
.Vb 2
\&  # Create your normal (non\-ordered alg:dep)
\&  my $dependency = Algorithm::Dependency\->new( ... );
\&  
\&  # Find the naive weight for an item
\&  my $weight = scalar($dependency\->schedule(\*(Aqitemname\*(Aq));
.Ve
.PP
\&\f(CW\*(C`Algorithm::Dependency::Weight\*(C'\fR 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.
.PP
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. \s-1BUT\s0 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.
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.ie n .SS "new @params"
.el .SS "new \f(CW@params\fP"
.IX Subsection "new @params"
The \f(CW\*(C`new\*(C'\fR constructor creates a new \f(CW\*(C`Algorithm::Dependency::Weight\*(C'\fR
object. It takes a number of key/value pairs as parameters (although
at the present time only one).
.ie n .IP "source => $Source" 4
.el .IP "source => \f(CW$Source\fR" 4
.IX Item "source => $Source"
The \f(CW\*(C`source\*(C'\fR 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.
.PP
Returns a new \f(CW\*(C`Algorithm::Dependency::Weight\*(C'\fR object, or \f(CW\*(C`undef\*(C'\fR on error.
.SS "source"
.IX Subsection "source"
The \f(CW\*(C`source\*(C'\fR accessor returns the source used for the weight calculations.
.PP
This will be either the one passed to the constructor, or the source from
inside the \f(CW\*(C`Algorithm::Dependency\*(C'\fR object passed as the \f(CW\*(C`source\*(C'\fR param
(\fBnot\fR the object itself, \fBits\fR source).
.ie n .SS "weight $name"
.el .SS "weight \f(CW$name\fP"
.IX Subsection "weight $name"
The \f(CW\*(C`weight\*(C'\fR method takes the name of a single item and calculates its
weight based on the configuration of the \f(CW\*(C`Algorithm::Dependency::Weight\*(C'\fR
object.
.PP
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 \f(CW\*(C`undef\*(C'\fR
on error.
.ie n .SS "weight_merged @names"
.el .SS "weight_merged \f(CW@names\fP"
.IX Subsection "weight_merged @names"
The \f(CW\*(C`weight_merged\*(C'\fR method takes the name of a set of items and
calculates an aggregated weight for the whole set.
.PP
Returns the weight as a scalar, or \f(CW\*(C`undef\*(C'\fR on error.
.ie n .SS "weight_hash @names"
.el .SS "weight_hash \f(CW@names\fP"
.IX Subsection "weight_hash @names"
The \f(CW\*(C`weight_hash\*(C'\fR method takes a list of item names, and calculates
their weights.
.PP
Returns a reference to a \f(CW\*(C`HASH\*(C'\fR with the item names as keys and weights
as values, or \f(CW\*(C`undef\*(C'\fR on error.
.SS "weight_all"
.IX Subsection "weight_all"
The \f(CW\*(C`weight_all\*(C'\fR 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.
.PP
Returns a reference to a \f(CW\*(C`HASH\*(C'\fR with the item names as keys and weights
as values, or \f(CW\*(C`undef\*(C'\fR on error.
.SH "TO DO"
.IX Header "TO DO"
\&\- Add support for non-naive weights via either custom code or method name
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm\-Dependency>
.PP
For general comments, contact the author.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithm::Dependency, Algorithm::Dependency::Source
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003 \- 2009 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.