1Algorithm::Dependency(3U)ser Contributed Perl DocumentatiAolngorithm::Dependency(3)
2
3
4

NAME

6       Algorithm::Dependency - Base class for implementing various dependency
7       trees
8

VERSION

10       version 1.112
11

SYNOPSIS

13       Typical Usage: Ordering based on dependency requirements
14
15         use Algorithm::Dependency::Ordered;
16         use Algorithm::Dependency::Source::HoA;
17
18         my $deps = {
19           core  => [ ],
20           a     => [ 'core' ],
21           b     => [ 'a' ]
22           this  => [ ],
23           that  => [ ],
24         };
25         my $deps_source = Algorithm::Dependency::Source::HoA->new( $deps );
26
27         my $dep = Algorithm::Dependency::Ordered->new(
28           source   => $deps_source,
29           selected => [ 'this', 'that' ], # Items we have processed elsewhere or have already satisfied
30         )
31         or die 'Failed to set up dependency algorithm';
32
33         my $also = $dep->schedule_all();
34         # Returns: ['core', 'a', 'b'] -- ie: installation-order. Whereas using base
35         # Algorithm::Dependency would return sorted ['a', 'b', 'core']
36
37         my $also = $dep->schedule( 'b' );
38         # Returns: ['core', 'a', 'b'] -- installation order, including ourselves
39
40         my $also = $dep->depends( 'b' );
41         # Returns: ['a', 'core'] -- sorted order, not including ourselves
42
43       Base Classes
44
45         use Algorithm::Dependency;
46         use Algorithm::Dependency::Source::File;
47
48         # Load the data from a simple text file
49         my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
50
51         # Create the dependency object, and indicate the items that are already
52         # selected/installed/etc in the database
53         my $dep = Algorithm::Dependency->new(
54             source   => $data_source,
55             selected => [ 'This', 'That' ]
56         ) or die 'Failed to set up dependency algorithm';
57
58         # For the item 'Foo', find out the other things we also have to select.
59         # This WON'T include the item we selected, 'Foo'.
60         my $also = $dep->depends( 'Foo' );
61         print $also
62               ? "By selecting 'Foo', you are also selecting the following items: "
63                       . join( ', ', @$also )
64               : "Nothing else to select for 'Foo'";
65
66         # Find out the order we need to act on the items in.
67         # This WILL include the item we selected, 'Foo'.
68         my $schedule = $dep->schedule( 'Foo' );
69

DESCRIPTION

71       Algorithm::Dependency is a framework for creating simple read-only
72       dependency hierarchies, where you have a set of items that rely on
73       other items in the set, and require actions on them as well.
74
75       Despite the most visible of these being software installation systems
76       like the CPAN installer, or Debian apt-get, they are useful in other
77       situations.  This module intentionally uses implementation-neutral
78       words, to avoid confusion.
79
80   Terminology
81       The term "ITEM" refers to a single entity, such as a single software
82       package, in the overall set of possible entities. Internally, this is a
83       fairly simple object. See Algorithm::Dependency::Item for details.
84
85       The term "SELECT" means that a particular item, for your purposes, has
86       already been acted up in the required way. For example, if the software
87       package had already been installed, and didn't need to be re-installed,
88       it would be "SELECTED".
89
90       The term "SOURCE" refers to a location that contains the master set of
91       items. This will be very application specific, and might be a flat
92       file, some form of database, the list of files in a folder, or
93       generated dynamically.
94
95   General Description
96       Algorithm::Dependency implements algorithms relating to dependency
97       hierarchies. To use this framework, all you need is a source for the
98       master list of all the items, and a list of those already selected. If
99       your dependency hierarchy doesn't require the concept of items that are
100       already selected, simply don't pass anything to the constructor for it.
101
102       Please note that the class Algorithm::Dependency does NOT implement an
103       ordering, for speed and simplicity reasons. That is, the "schedule" it
104       provides is not in any particular order. If item 'A' depends on item
105       'B', it will not place B before A in the schedule. This makes it
106       unsuitable for things like software installers, as they typically would
107       need B to be installed before A, or the installation of A would fail.
108
109       For dependency hierarchies requiring the items to be acted on in a
110       particular order, either top down or bottom up, see
111       Algorithm::Dependency::Ordered.  It should be more applicable for your
112       needs. This is the the subclass you would probably use to implement a
113       simple ( non-versioned ) package installation system. Please note that
114       an ordered hierarchy has additional constraints. For example, circular
115       dependencies ARE legal in a non-ordered hierarchy, but ARE NOT legal in
116       an ordered hierarchy.
117
118   Extending
119       A module for creating a source from a simple flat file is included. For
120       details see Algorithm::Dependency::Source::File. Information on
121       creating a source for your particular use is in
122       Algorithm::Dependency::Source.
123

METHODS

125   new %args
126       The constructor creates a new context object for the dependency
127       algorithms to act in. It takes as argument a series of options for
128       creating the object.
129
130       source => $Source
131           The only compulsory option is the source of the dependency items.
132           This is an object of a subclass of Algorithm::Dependency::Source.
133           In practical terms, this means you will create the source object
134           before creating the Algorithm::Dependency object.
135
136       selected => [ 'A', 'B', 'C', etc... ]
137           The "selected" option provides a list of those items that have
138           already been 'selected', acted upon, installed, or whatever. If
139           another item depends on one in this list, we don't have to include
140           it in the output of the "schedule" or "depends" methods.
141
142       ignore_orphans => 1
143           Normally, the item source is expected to be largely perfect and
144           error free.  An 'orphan' is an item name that appears as a
145           dependency of another item, but doesn't exist, or has been deleted.
146
147           By providing the "ignore_orphans" flag, orphans are simply ignored.
148           Without the "ignore_orphans" flag, an error will be returned if an
149           orphan is found.
150
151       The "new" constructor returns a new Algorithm::Dependency object on
152       success, or "undef" on error.
153
154   source
155       The "source" method retrieves the Algorithm::Dependency::Source object
156       for the algorithm context.
157
158   selected_list
159       The "selected_list" method returns, as a list and in alphabetical
160       order, the list of the names of the selected items.
161
162   selected $name
163       Given an item name, the "selected" method will return true if the item
164       is selected, false is not, or "undef" if the item does not exist, or an
165       error occurs.
166
167   item $name
168       The "item" method fetches and returns the item object, as specified by
169       the name argument.
170
171       Returns an Algorithm::Dependency::Item object on success, or "undef" if
172       an item does not exist for the argument provided.
173
174   depends $name1, ..., $nameN
175       Given a list of one or more item names, the "depends" method will
176       return a reference to an array containing a list of the names of all
177       the OTHER items that also have to be selected to meet dependencies.
178
179       That is, if item A depends on B and C then the "depends" method would
180       return a reference to an array with B and C. ( "[ 'B', 'C' ]" )
181
182       If multiple item names are provided, the same applies. The list
183       returned will not contain duplicates.
184
185       The method returns a reference to an array of item names on success, a
186       reference to an empty array if no other items are needed, or "undef" on
187       error.
188
189       NOTE: The result of "depends" is ordered by an internal "sort"
190       irrespective of the ordering provided by the dependency handler.  Use
191       Algorithm::Dependency::Ordered and "schedule" to use the most common
192       ordering (process sequence)
193
194   schedule $name1, ..., $nameN
195       Given a list of one or more item names, the "depends" method will
196       return, as a reference to an array, the ordered list of items you
197       should act upon in whichever order this particular dependency handler
198       uses - see Algorithm::Dependency::Ordered for one that implements the
199       most common ordering (process sequence).
200
201       This would be the original names provided, plus those added to satisfy
202       dependencies, in the preferred order of action. For the normal
203       algorithm, where order it not important, this is alphabetical order.
204       This makes it easier for someone watching a program operate on the
205       items to determine how far you are through the task and makes any logs
206       easier to read.
207
208       If any of the names you provided in the arguments is already selected,
209       it will not be included in the list.
210
211       The method returns a reference to an array of item names on success, a
212       reference to an empty array if no items need to be acted upon, or
213       "undef" on error.
214
215   schedule_all;
216       The "schedule_all" method acts the same as the "schedule" method, but
217       returns a schedule that selected all the so-far unselected items.
218

TO DO

220       Add the "check_source" method, to verify the integrity of the source.
221
222       Possibly add Algorithm::Dependency::Versions, to implement an ordered
223       dependency tree with versions, like for perl modules.
224
225       Currently readonly. Make the whole thing writable, so the module can be
226       used as the core of an actual dependency application, as opposed to
227       just being a tool.
228

SEE ALSO

230       Algorithm::Dependency::Ordered, Algorithm::Dependency::Item,
231       Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
232

SUPPORT

234       Bugs may be submitted through the RT bug tracker
235       <https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-
236       Dependency> (or bug-Algorithm-Dependency@rt.cpan.org <mailto:bug-
237       Algorithm-Dependency@rt.cpan.org>).
238

AUTHOR

240       Adam Kennedy <adamk@cpan.org>
241

CONTRIBUTORS

243       •   Adam Kennedy <adam@ali.as>
244
245       •   Karen Etheridge <ether@cpan.org>
246
247       •   Mark Murawski <markm@intellasoft.net>
248
250       This software is copyright (c) 2003 by Adam Kennedy.
251
252       This is free software; you can redistribute it and/or modify it under
253       the same terms as the Perl 5 programming language system itself.
254
255
256
257perl v5.36.0                      2023-01-19          Algorithm::Dependency(3)
Impressum