Algorithm::Dependency(3pm)

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

SYNOPSIS

10         use Algorithm::Dependency;
11         use Algorithm::Dependency::Source::File;
12
13         # Load the data from a simple text file
14         my $data_source = Algorithm::Dependency::Source::File->new( 'foo.txt' );
15
16         # Create the dependency object, and indicate the items that are already
17         # selected/installed/etc in the database
18         my $dep = Algorithm::Dependency->new(
19             source   => $data_source,
20             selected => [ 'This', 'That' ]
21             ) or die 'Failed to set up dependency algorithm';
22
23         # For the item 'Foo', find out the other things we also have to select.
24         # This WON'T include the item we selected, 'Foo'.
25         my $also = $dep->depends( 'Foo' );
26         print $also
27               ? "By selecting 'Foo', you are also selecting the following items: "
28                       . join( ', ', @$also )
29               : "Nothing else to select for 'Foo'";
30
31         # Find out the order we need to act on the items in.
32         # This WILL include the item we selected, 'Foo'.
33         my $schedule = $dep->schedule( 'Foo' );
34

DESCRIPTION

36       Algorithm::Dependency is a framework for creating simple read-only
37       dependency heirachies, where you have a set of items that rely on other
38       items in the set, and require actions on them as well.
39
40       Despite the most visible of these being software installation systems
41       like the CPAN installer, or debian apt-get, they are usefull in other
42       situations.  This module intentionally uses implementation-neutral
43       words, to avoid confusion.
44
45       Terminology
46
47       The term "ITEM" refers to a single entity, such as a single software
48       package, in the overall set of possible entities. Internally, this is a
49       fairly simple object. See Algorithm::Dependency::Item for details.
50
51       The term "SELECT" means that a particular item, for your purposes, has
52       already been acted up in the required way. For example, if the software
53       package had already been installed, and didn't need to be re-installed,
54       it would be "SELECTED".
55
56       The term "SOURCE" refers to a location that contains the master set of
57       items. This will be very application specific, and might be a flat
58       file, some form of database, the list of files in a folder, or gener‐
59       ated dynamically.
60
61       General Description
62
63       Algorithm::Dependency implements algorithms relating to dependency
64       heirachies. To use this framework, all you need is a source for the
65       master list of all the items, and a list of those already selected. If
66       your dependency heirachy doesn't require the concept of items that are
67       already selected, simply don't pass anything to the constructor for it.
68
69       Please note that the class Algorithm::Dependency does NOT implement an
70       ordering, for speed and simplicity reasons. That is, the "schedule" it
71       provides is not in any particular order. If item 'A' depends on item
72       'B', it will not place B before A in the schedule. This makes it
73       unsuitable for things like software installers, as they typically would
74       need B to be installed before A, or the installation of A would fail.
75
76       For dependency heirachies requiring the items to be acted on in a par‐
77       ticular order, either top down or bottom up, see Algorithm::Depen‐
78       dency::Ordered.  It should be more applicable for your needs. This is
79       the the subclass you would probably use to implement a simple ( non-
80       versioned ) package installation system. Please note that an ordered
81       heirachy has additional constraints. For example, circular dependencies
82       ARE legal in a non-ordered heirachy, but ARE NOT legal in an ordered
83       heirachy.
84
85       Extending
86
87       A module for creating a source from a simple flat file is included. For
88       details see Algorithm::Dependency::Source::File. Information on creat‐
89       ing a source for your particular use is in Algorithm::Depen‐
90       dency::Source.
91

METHODS

93       new %args
94
95       The constructor creates a new context object for the dependency algo‐
96       rithms to act in. It takes as argument a series of options for creating
97       the object.
98
99       source => $Source
100           The only compulsory option is the source of the dependency items.
101           This is an object of a subclass of Algorithm::Dependency::Source.
102           In practical terms, this means you will create the source object
103           before creating the Algorithm::Dependency object.
104
105       selected => [ 'A', 'B', 'C', etc... ]
106           The "selected" option provides a list of those items that have
107           already been 'selected', acted upon, installed, or whatever. If
108           another item depends on one in this list, we don't have to include
109           it in the output of the "schedule" or "depends" methods.
110
111       ignore_orphans => 1
112           Normally, the item source is expected to be largely perfect and
113           error free.  An 'orphan' is an item name that appears as a depen‐
114           dency of another item, but doesn't exist, or has been deleted.
115
116           By providing the "ignore_orphans" flag, orphans are simply ignored.
117           Without the "ignore_orphans" flag, an error will be returned if an
118           orphan is found.
119
120       The "new" constructor returns a new Algorithm::Dependency object on
121       success, or "undef" on error.
122
123       source
124
125       The "source" method retrieves the Algorithm::Dependency::Source object
126       for the algorithm context.
127
128       selected_list
129
130       The "selected_list" method returns, as a list and in alphabetical
131       order, the list of the names of the selected items.
132
133       selected $name
134
135       Given an item name, the "selected" method will return true if the item
136       is selected, false is not, or "undef" if the item does not exist, or an
137       error occurs.
138
139       item $name
140
141       The "item" method fetches and returns the item object, as specified by
142       the name argument.
143
144       Returns an Algorithm::Dependency::Item object on success, or "undef" if
145       an item does not exist for the argument provided.
146
147       depends $name1, ..., $nameN
148
149       Given a list of one or more item names, the "depends" method will
150       return a reference to an array containing a list of the names of all
151       the OTHER items that also have to be selected to meet dependencies.
152
153       That is, if item A depends on B and C then the "depends" method would
154       return a reference to an array with B and C. ( "[ 'B', 'C' ]" )
155
156       If multiple item names are provided, the same applies. The list
157       returned will not contain duplicates.
158
159       The method returns a reference to an array of item names on success, a
160       reference to an empty array if no other items are needed, or "undef" on
161       error.
162
163       schedule $name1, ..., $nameN
164
165       Given a list of one or more item names, the "depends" method will
166       return, as a reference to an array, the ordered list of items you
167       should act upon.
168
169       This would be the original names provided, plus those added to satisfy
170       dependencies, in the prefered order of action. For the normal algo‐
171       rithm, where order it not important, this is alphabetical order. This
172       makes it easier for someone watching a program operate on the items to
173       determine how far you are through the task and makes any logs easier to
174       read.
175
176       If any of the names you provided in the arguments is already selected,
177       it will not be included in the list.
178
179       The method returns a reference to an array of item names on success, a
180       reference to an empty array if no items need to be acted upon, or
181       "undef" on error.
182
183       schedule_all;
184
185       The "schedule_all" method acts the same as the "schedule" method, but
186       returns a schedule that selected all the so-far unselected items.
187

TO DO

189       Add the "check_source" method, to verify the integrity of the source.
190
191       Possibly add Algorithm::Dependency::Versions, to implement an ordered
192       dependency tree with versions, like for perl modules.
193
194       Currently readonly. Make the whole thing writable, so the module can be
195       used as the core of an actual dependency application, as opposed to
196       just being a tool.
197

SUPPORT

199       Bugs should be submitted via the CPAN bug tracker, located at
200
201       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Dependency>
202
203       For general comments, contact the author.
204

AUTHOR

206       Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
207

COPYRIGHT

213       Copyright (c) 2003 - 2005 Adam Kennedy.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.
217
218       The full text of the license can be found in the LICENSE file included
219       with this module.
220
221
222
223perl v5.8.8                       2008-01-14          Algorithm::Dependency(3)