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.