NAME¶
Algorithm::Dependency - Base class for implementing various dependency trees
SYNOPSIS¶
use Algorithm::Dependency;
use Algorithm::Dependency::Source::File;
# Load the data from a simple text file
my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
# Create the dependency object, and indicate the items that are already
# selected/installed/etc in the database
my $dep = Algorithm::Dependency->new(
source => $data_source,
selected => [ 'This', 'That' ]
) or die 'Failed to set up dependency algorithm';
# For the item 'Foo', find out the other things we also have to select.
# This WON'T include the item we selected, 'Foo'.
my $also = $dep->depends( 'Foo' );
print $also
? "By selecting 'Foo', you are also selecting the following items: "
. join( ', ', @$also )
: "Nothing else to select for 'Foo'";
# Find out the order we need to act on the items in.
# This WILL include the item we selected, 'Foo'.
my $schedule = $dep->schedule( 'Foo' );
DESCRIPTION¶
Algorithm::Dependency is a framework for creating simple read-only dependency
heirachies, where you have a set of items that rely on other items in the set,
and require actions on them as well.
Despite the most visible of these being software installation systems like the
CPAN installer, or debian apt-get, they are usefull in other situations. This
module intentionally uses implementation-neutral words, to avoid confusion.
Terminology¶
The term "ITEM" refers to a single entity, such as a single software
package, in the overall set of possible entities. Internally, this is a fairly
simple object. See Algorithm::Dependency::Item for details.
The term "SELECT" means that a particular item, for your purposes, has
already been acted up in the required way. For example, if the software
package had already been installed, and didn't need to be re-installed, it
would be "SELECTED".
The term "SOURCE" refers to a location that contains the master set of
items. This will be very application specific, and might be a flat file, some
form of database, the list of files in a folder, or generated dynamically.
General Description¶
Algorithm::Dependency implements algorithms relating to dependency heirachies.
To use this framework, all you need is a source for the master list of all the
items, and a list of those already selected. If your dependency heirachy
doesn't require the concept of items that are already selected, simply don't
pass anything to the constructor for it.
Please note that the class Algorithm::Dependency does NOT implement an ordering,
for speed and simplicity reasons. That is, the "schedule" it
provides is not in any particular order. If item 'A' depends on item 'B', it
will not place B before A in the schedule. This makes it unsuitable for things
like software installers, as they typically would need B to be installed
before A, or the installation of A would fail.
For dependency heirachies requiring the items to be acted on in a particular
order, either top down or bottom up, see Algorithm::Dependency::Ordered. It
should be more applicable for your needs. This is the the subclass you would
probably use to implement a simple ( non-versioned ) package installation
system. Please note that an ordered heirachy has additional constraints. For
example, circular dependencies ARE legal in a non-ordered heirachy, but ARE
NOT legal in an ordered heirachy.
Extending¶
A module for creating a source from a simple flat file is included. For details
see Algorithm::Dependency::Source::File. Information on creating a source for
your particular use is in Algorithm::Dependency::Source.
METHODS¶
new %args¶
The constructor creates a new context object for the dependency algorithms to
act in. It takes as argument a series of options for creating the object.
- source => $Source
- The only compulsory option is the source of the dependency items. This is
an object of a subclass of Algorithm::Dependency::Source. In practical
terms, this means you will create the source object before creating the
Algorithm::Dependency object.
- selected => [ 'A', 'B', 'C', etc... ]
- The "selected" option provides a list of those items that have
already been 'selected', acted upon, installed, or whatever. If another
item depends on one in this list, we don't have to include it in the
output of the "schedule" or "depends" methods.
- ignore_orphans => 1
- Normally, the item source is expected to be largely perfect and error
free. An 'orphan' is an item name that appears as a dependency of another
item, but doesn't exist, or has been deleted.
By providing the "ignore_orphans" flag, orphans are simply
ignored. Without the "ignore_orphans" flag, an error will be
returned if an orphan is found.
The "new" constructor returns a new Algorithm::Dependency object on
success, or "undef" on error.
source¶
The "source" method retrieves the Algorithm::Dependency::Source object
for the algorithm context.
selected_list¶
The "selected_list" method returns, as a list and in alphabetical
order, the list of the names of the selected items.
selected $name¶
Given an item name, the "selected" method will return true if the item
is selected, false is not, or "undef" if the item does not exist, or
an error occurs.
item $name¶
The "item" method fetches and returns the item object, as specified by
the name argument.
Returns an Algorithm::Dependency::Item object on success, or "undef"
if an item does not exist for the argument provided.
depends $name1, ..., $nameN¶
Given a list of one or more item names, the "depends" method will
return a reference to an array containing a list of the names of all the OTHER
items that also have to be selected to meet dependencies.
That is, if item A depends on B and C then the "depends" method would
return a reference to an array with B and C. ( "[ 'B', 'C' ]" )
If multiple item names are provided, the same applies. The list returned will
not contain duplicates.
The method returns a reference to an array of item names on success, a reference
to an empty array if no other items are needed, or "undef" on error.
schedule $name1, ..., $nameN¶
Given a list of one or more item names, the "depends" method will
return, as a reference to an array, the ordered list of items you should act
upon.
This would be the original names provided, plus those added to satisfy
dependencies, in the prefered order of action. For the normal algorithm, where
order it not important, this is alphabetical order. This makes it easier for
someone watching a program operate on the items to determine how far you are
through the task and makes any logs easier to read.
If any of the names you provided in the arguments is already selected, it will
not be included in the list.
The method returns a reference to an array of item names on success, a reference
to an empty array if no items need to be acted upon, or "undef" on
error.
schedule_all;¶
The "schedule_all" method acts the same as the "schedule"
method, but returns a schedule that selected all the so-far unselected items.
TO DO¶
Add the "check_source" method, to verify the integrity of the source.
Possibly add Algorithm::Dependency::Versions, to implement an ordered dependency
tree with versions, like for perl modules.
Currently readonly. Make the whole thing writable, so the module can be used as
the core of an actual dependency application, as opposed to just being a tool.
SUPPORT¶
Bugs should be submitted via the CPAN bug tracker, located at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Dependency
<
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::Ordered, Algorithm::Dependency::Item,
Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
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.