1Algorithm::Dependency(3U)ser Contributed Perl DocumentatiAolngorithm::Dependency(3)
2
6 Algorithm::Dependency - Base class for implementing various dependency
7 trees
8
10 version 1.112
11
13 Typical Usage: Ordering based on dependency requirements
14 use Algorithm::Dependency::Ordered;
16 use Algorithm::Dependency::Source::HoA;
17 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 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 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 my $also = $dep->schedule( 'b' );
38 # Returns: ['core', 'a', 'b'] -- installation order, including ourselves
39 my $also = $dep->depends( 'b' );
41 # Returns: ['a', 'core'] -- sorted order, not including ourselves
42 Base Classes
44 use Algorithm::Dependency;
46 use Algorithm::Dependency::Source::File;
47 # Load the data from a simple text file
49 my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
50 # 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 # 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 # 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
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 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 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 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 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 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 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 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 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
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 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 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 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 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 The "new" constructor returns a new Algorithm::Dependency object on
152 success, or "undef" on error.
153 source
155 The "source" method retrieves the Algorithm::Dependency::Source object
156 for the algorithm context.
157 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 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 item $name
168 The "item" method fetches and returns the item object, as specified by
169 the name argument.
170 Returns an Algorithm::Dependency::Item object on success, or "undef" if
172 an item does not exist for the argument provided.
173 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 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 If multiple item names are provided, the same applies. The list
183 returned will not contain duplicates.
184 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 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 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 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 If any of the names you provided in the arguments is already selected,
209 it will not be included in the list.
210 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 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
220 Add the "check_source" method, to verify the integrity of the source.
221 Possibly add Algorithm::Dependency::Versions, to implement an ordered
223 dependency tree with versions, like for perl modules.
224 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
230 Algorithm::Dependency::Ordered, Algorithm::Dependency::Item,
231 Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
232
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
240 Adam Kennedy <adamk@cpan.org>
241
243 • Adam Kennedy <adam@ali.as>
244 • Karen Etheridge <ether@cpan.org>
246 • Mark Murawski <markm@intellasoft.net>
248
250 This software is copyright (c) 2003 by Adam Kennedy.
251 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.
254perl v5.34.0 2021-10-13 Algorithm::Dependency(3)