Algori...endency(3pm)

📦
version 1.112 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 Algorithm::Dependency — the dependency-tree base class bestie 💖

okay so you found the 3pm page, the Perl one, version 1.112, and honestly? you're about to have a great time. this is Algorithm::Dependency, and it's giving "let me build you a dependency tree" in the most iconic way possible. sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

Algorithm::Dependency — the base class you inherit from when you wanna implement all sorts of dependency trees. yes, base class, she's the blueprint, the main character energy that other modules build on 👑

🎀 VERSION 🎀

version 1.112 — that's the one, no cap.

🌸 SYNOPSIS 🌸

Typical Usage: Ordering based on dependency requirements

okay so here's the classic scenario, bestie. we want stuff installed in an order that actually makes sense:

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

and here's the bare-bones version, using the base classes directly 🦋:

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 building simple read-only dependency hierarchies — meaning you've got a set of items, and some of those items rely on other items in the same set, and you also need to do things to them. periodt.

now, the most obvious place you see this is software installers — like the CPAN installer, or Debian's apt-get 💅 — but bestie, this stuff is useful in so many other situations too. that's why this module deliberately uses implementation-neutral words. no confusion allowed, we keep the vocabulary clean ✨.

Terminology 🧚

  • ITEM — a single entity, like one software package, sitting inside the overall set of all possible entities. internally it's a pretty simple object. go look at Algorithm::Dependency::Item for the deets.
  • SELECT — means that a particular item, for your purposes, has already been acted upon in the required way. like, if a software package is already installed and doesn't need reinstalling, it's SELECTED. she's done, she's served her purpose 💅.
  • SOURCE — a location that holds the master set of items. this is super application specific, ngl. it might be a flat file, some kind of database, a list of files in a folder, or generated dynamically. you do you boo.

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, plus a list of the ones already selected. and if your dependency hierarchy doesn't even need the concept of already-selected items? just don't pass anything to the constructor for it. simple as that 🫶.

⚠️ okay important heads-up bestie: the class Algorithm::Dependency does NOT implement an ordering. not at all. and that's for speed and simplicity reasons, okay?? that means the schedule it gives you is not in any particular order. if item 'A' depends on item 'B', it will not place B before A in the schedule. so yeah — this makes it unsuitable for things like software installers, because those typically need B installed before A, otherwise the installation of A just fails. 😭

for dependency hierarchies that DO require items to be acted on in a particular order — top down or bottom up — go see Algorithm::Dependency::Ordered. that one's more applicable to your needs. it's the the subclass you'd probably use to build a simple (non-versioned) package installation system. and please note: an ordered hierarchy has additional constraints. like, circular dependencies ARE legal in a non-ordered hierarchy, but ARE NOT legal in an ordered hierarchy. that's just the rules 🔥.

Extending 🌟

there's a module included for creating a source from a simple flat file — full details in Algorithm::Dependency::Source::File. and if you wanna know how to create a source for your particular use case, that lives in Algorithm::Dependency::Source. slay.

💅 METHODS 💅

new %args

the constructor. she creates a new context object for the dependency algorithms to act in. takes a series of options for creating the object as her arguments.

  • source => $Source — the only compulsory option, bestie. this is the source of the dependency items, and it's an object of a subclass of Algorithm::Dependency::Source. in practical terms? that means you create the source object before you create the Algorithm::Dependency object. order matters, always ✨.
  • selected => [ 'A', 'B', 'C', etc... ] — the selected option gives you a list of those items that have already been 'selected', acted upon, installed, or whatever else. 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. free real estate 💖.
  • ignore_orphans => 1 — normally, the item source is expected to be largely perfect and error free. an 'orphan' is an item name that shows up 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. she's right there. go get her 🎀.

selected_list

the selected_list method returns, as a list and in alphabetical order, the list of the names of the selected items. alphabetical, because we're organized queens 👑.

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. three possibilities, three vibes.

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. no dupes, we don't do that here 🚫.

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). iykyk.

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. and honestly? that's a gift, because it makes it way easier for someone watching a program operate on the items to figure out how far through the task you are, and it makes any logs easier to read. we love readable logs 💖.

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. she does the whole thing. all of it. every last one 🌈.

🦋 TO DO 🦋

the wishlist, the little "one day" board, we love her:

  • 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.

🌟 SEE ALSO 🌟

Algorithm::Dependency::Ordered, Algorithm::Dependency::Item, Algorithm::Dependency::Source, Algorithm::Dependency::Source::File

go read those too, bestie, they're all part of the family 🫶.

💜 SUPPORT 💜

bugs may be submitted through the RT bug tracker at https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-Dependency (or at 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>

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. so go wild, legally 💅.

and that's the whole page, bestie!! 💖 this beauty was documented for Perl v5.40.1 and stamped 2025-09-18 — so when you're out here slaying your dependency trees, remember who told you first. mwah 🫶✨

📦 where this page comes from