Ubuntu Manpage: Algorithm::Dependency - Base class for implementing various dependency trees

Provided by: libalgorithm-dependency-perl_1.112-1_all

NAME

       Algorithm::Dependency - Base class for implementing various dependency trees

VERSION

       version 1.112

SYNOPSIS

       Typical Usage: Ordering based on dependency requirements

         use Algorithm::Dependency::Ordered;
         use Algorithm::Dependency::Source::HoA;

         my $deps = {
           core  => [ ],
           a     => [ 'core' ],
           b     => [ 'a' ]
           this  => [ ],
           that  => [ ],
         };
         my $deps_source = Algorithm::Dependency::Source::HoA->new( $deps );

         my $dep = Algorithm::Dependency::Ordered->new(
           source   => $deps_source,
           selected => [ 'this', 'that' ], # Items we have processed elsewhere or have already satisfied
         )
         or die 'Failed to set up dependency algorithm';

         my $also = $dep->schedule_all();
         # Returns: ['core', 'a', 'b'] -- ie: installation-order. Whereas using base
         # Algorithm::Dependency would return sorted ['a', 'b', 'core']

         my $also = $dep->schedule( 'b' );
         # Returns: ['core', 'a', 'b'] -- installation order, including ourselves

         my $also = $dep->depends( 'b' );
         # Returns: ['a', 'core'] -- sorted order, not including ourselves

       Base Classes

         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 hierarchies, 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 useful 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 hierarchies. 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 hierarchy 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 hierarchies 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 hierarchy has additional constraints. For example, circular dependencies ARE
       legal in a non-ordered hierarchy, but ARE NOT legal in an ordered hierarchy.

   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.

NOTE: The result of "depends" is ordered by an internal "sort" irrespective of the ordering provided by
the dependency handler. Use Algorithm::Dependency::Ordered and "schedule" to use the most common
ordering (process sequence)

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 in whichever order this particular dependency handler uses -
see Algorithm::Dependency::Ordered for one that implements the most common ordering (process sequence).

This would be the original names provided, plus those added to satisfy dependencies, in the preferred
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        may        be        submitted        through        the        RT        bug         tracker
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-Dependency>                              (or
       bug-Algorithm-Dependency@rt.cpan.org <mailto:bug-Algorithm-Dependency@rt.cpan.org>).

AUTHOR

       Adam Kennedy <adamk@cpan.org>

CONTRIBUTORS

       •   Adam Kennedy <adam@ali.as>

       •   Karen Etheridge <ether@cpan.org>

       •   Mark Murawski <markm@intellasoft.net>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2003 by Adam Kennedy.

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

perl v5.40.1                                       2025-09-18                         Algorithm::Dependency(3pm)