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>

   For general comments, contact the author.

AUTHOR
   Adam Kennedy <[email protected]>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.