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.111
11

SYNOPSIS

13         use Algorithm::Dependency;
14         use Algorithm::Dependency::Source::File;
15
16         # Load the data from a simple text file
17         my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
18
19         # 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
26         # 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
34         # 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

DESCRIPTION

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
43       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
48   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
53       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
58       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
63   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
70       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
77       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
86   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

METHODS

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
98       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
104       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
110       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
115           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
119       The "new" constructor returns a new Algorithm::Dependency object on
120       success, or "undef" on error.
121
122   source
123       The "source" method retrieves the Algorithm::Dependency::Source object
124       for the algorithm context.
125
126   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
130   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
135   item $name
136       The "item" method fetches and returns the item object, as specified by
137       the name argument.
138
139       Returns an Algorithm::Dependency::Item object on success, or "undef" if
140       an item does not exist for the argument provided.
141
142   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
147       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
150       If multiple item names are provided, the same applies. The list
151       returned will not contain duplicates.
152
153       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
157   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
162       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
169       If any of the names you provided in the arguments is already selected,
170       it will not be included in the list.
171
172       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
176   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

TO DO

181       Add the "check_source" method, to verify the integrity of the source.
182
183       Possibly add Algorithm::Dependency::Versions, to implement an ordered
184       dependency tree with versions, like for perl modules.
185
186       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

SEE ALSO

191       Algorithm::Dependency::Ordered, Algorithm::Dependency::Item,
192       Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
193

SUPPORT

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

AUTHOR

201       Adam Kennedy <adamk@cpan.org>
202

CONTRIBUTORS

204       •   Adam Kennedy <adam@ali.as>
205
206       •   Karen Etheridge <ether@cpan.org>
207
209       This software is copyright (c) 2003 by Adam Kennedy.
210
211       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.
213
214
215
216perl v5.32.1                      2021-01-26          Algorithm::Dependency(3)
Impressum