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.111
11
13 use Algorithm::Dependency;
14 use Algorithm::Dependency::Source::File;
15 # Load the data from a simple text file
17 my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
18 # Create the dependency object, and indicate the items that are already
20 # selected/installed/etc in the database
21 my $dep = Algorithm::Dependency->new(
22 source => $data_source,
23 selected => [ 'This', 'That' ]
24 ) or die 'Failed to set up dependency algorithm';
25 # For the item 'Foo', find out the other things we also have to select.
27 # This WON'T include the item we selected, 'Foo'.
28 my $also = $dep->depends( 'Foo' );
29 print $also
30 ? "By selecting 'Foo', you are also selecting the following items: "
31 . join( ', ', @$also )
32 : "Nothing else to select for 'Foo'";
33 # Find out the order we need to act on the items in.
35 # This WILL include the item we selected, 'Foo'.
36 my $schedule = $dep->schedule( 'Foo' );
37
39 Algorithm::Dependency is a framework for creating simple read-only
40 dependency hierarchies, where you have a set of items that rely on
41 other items in the set, and require actions on them as well.
42 Despite the most visible of these being software installation systems
44 like the CPAN installer, or Debian apt-get, they are useful in other
45 situations. This module intentionally uses implementation-neutral
46 words, to avoid confusion.
47 Terminology
49 The term "ITEM" refers to a single entity, such as a single software
50 package, in the overall set of possible entities. Internally, this is a
51 fairly simple object. See Algorithm::Dependency::Item for details.
52 The term "SELECT" means that a particular item, for your purposes, has
54 already been acted up in the required way. For example, if the software
55 package had already been installed, and didn't need to be re-installed,
56 it would be "SELECTED".
57 The term "SOURCE" refers to a location that contains the master set of
59 items. This will be very application specific, and might be a flat
60 file, some form of database, the list of files in a folder, or
61 generated dynamically.
62 General Description
64 Algorithm::Dependency implements algorithms relating to dependency
65 hierarchies. To use this framework, all you need is a source for the
66 master list of all the items, and a list of those already selected. If
67 your dependency hierarchy doesn't require the concept of items that are
68 already selected, simply don't pass anything to the constructor for it.
69 Please note that the class Algorithm::Dependency does NOT implement an
71 ordering, for speed and simplicity reasons. That is, the "schedule" it
72 provides is not in any particular order. If item 'A' depends on item
73 'B', it will not place B before A in the schedule. This makes it
74 unsuitable for things like software installers, as they typically would
75 need B to be installed before A, or the installation of A would fail.
76 For dependency hierarchies requiring the items to be acted on in a
78 particular order, either top down or bottom up, see
79 Algorithm::Dependency::Ordered. It should be more applicable for your
80 needs. This is the the subclass you would probably use to implement a
81 simple ( non-versioned ) package installation system. Please note that
82 an ordered hierarchy has additional constraints. For example, circular
83 dependencies ARE legal in a non-ordered hierarchy, but ARE NOT legal in
84 an ordered hierarchy.
85 Extending
87 A module for creating a source from a simple flat file is included. For
88 details see Algorithm::Dependency::Source::File. Information on
89 creating a source for your particular use is in
90 Algorithm::Dependency::Source.
91
93 new %args
94 The constructor creates a new context object for the dependency
95 algorithms to act in. It takes as argument a series of options for
96 creating the object.
97 source => $Source
99 The only compulsory option is the source of the dependency items.
100 This is an object of a subclass of Algorithm::Dependency::Source.
101 In practical terms, this means you will create the source object
102 before creating the Algorithm::Dependency object.
103 selected => [ 'A', 'B', 'C', etc... ]
105 The "selected" option provides a list of those items that have
106 already been 'selected', acted upon, installed, or whatever. If
107 another item depends on one in this list, we don't have to include
108 it in the output of the "schedule" or "depends" methods.
109 ignore_orphans => 1
111 Normally, the item source is expected to be largely perfect and
112 error free. An 'orphan' is an item name that appears as a
113 dependency of another item, but doesn't exist, or has been deleted.
114 By providing the "ignore_orphans" flag, orphans are simply ignored.
116 Without the "ignore_orphans" flag, an error will be returned if an
117 orphan is found.
118 The "new" constructor returns a new Algorithm::Dependency object on
120 success, or "undef" on error.
121 source
123 The "source" method retrieves the Algorithm::Dependency::Source object
124 for the algorithm context.
125 selected_list
127 The "selected_list" method returns, as a list and in alphabetical
128 order, the list of the names of the selected items.
129 selected $name
131 Given an item name, the "selected" method will return true if the item
132 is selected, false is not, or "undef" if the item does not exist, or an
133 error occurs.
134 item $name
136 The "item" method fetches and returns the item object, as specified by
137 the name argument.
138 Returns an Algorithm::Dependency::Item object on success, or "undef" if
140 an item does not exist for the argument provided.
141 depends $name1, ..., $nameN
143 Given a list of one or more item names, the "depends" method will
144 return a reference to an array containing a list of the names of all
145 the OTHER items that also have to be selected to meet dependencies.
146 That is, if item A depends on B and C then the "depends" method would
148 return a reference to an array with B and C. ( "[ 'B', 'C' ]" )
149 If multiple item names are provided, the same applies. The list
151 returned will not contain duplicates.
152 The method returns a reference to an array of item names on success, a
154 reference to an empty array if no other items are needed, or "undef" on
155 error.
156 schedule $name1, ..., $nameN
158 Given a list of one or more item names, the "depends" method will
159 return, as a reference to an array, the ordered list of items you
160 should act upon.
161 This would be the original names provided, plus those added to satisfy
163 dependencies, in the preferred order of action. For the normal
164 algorithm, where order it not important, this is alphabetical order.
165 This makes it easier for someone watching a program operate on the
166 items to determine how far you are through the task and makes any logs
167 easier to read.
168 If any of the names you provided in the arguments is already selected,
170 it will not be included in the list.
171 The method returns a reference to an array of item names on success, a
173 reference to an empty array if no items need to be acted upon, or
174 "undef" on error.
175 schedule_all;
177 The "schedule_all" method acts the same as the "schedule" method, but
178 returns a schedule that selected all the so-far unselected items.
179
181 Add the "check_source" method, to verify the integrity of the source.
182 Possibly add Algorithm::Dependency::Versions, to implement an ordered
184 dependency tree with versions, like for perl modules.
185 Currently readonly. Make the whole thing writable, so the module can be
187 used as the core of an actual dependency application, as opposed to
188 just being a tool.
189
191 Algorithm::Dependency::Ordered, Algorithm::Dependency::Item,
192 Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
193
195 Bugs may be submitted through the RT bug tracker
196 <https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-
197 Dependency> (or bug-Algorithm-Dependency@rt.cpan.org <mailto:bug-
198 Algorithm-Dependency@rt.cpan.org>).
199
201 Adam Kennedy <adamk@cpan.org>
202
204 • Adam Kennedy <adam@ali.as>
205 • Karen Etheridge <ether@cpan.org>
207
209 This software is copyright (c) 2003 by Adam Kennedy.
210 This is free software; you can redistribute it and/or modify it under
212 the same terms as the Perl 5 programming language system itself.
213perl v5.32.1 2021-01-26 Algorithm::Dependency(3)