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       The term "ITEM" refers to a single entity, such as a single software
47       package, in the overall set of possible entities. Internally, this is a
48       fairly simple object. See Algorithm::Dependency::Item for details.
49
50       The term "SELECT" means that a particular item, for your purposes, has
51       already been acted up in the required way. For example, if the software
52       package had already been installed, and didn't need to be re-installed,
53       it would be "SELECTED".
54
55       The term "SOURCE" refers to a location that contains the master set of
56       items. This will be very application specific, and might be a flat
57       file, some form of database, the list of files in a folder, or
58       generated dynamically.
59
60   General Description
61       Algorithm::Dependency implements algorithms relating to dependency
62       heirachies. To use this framework, all you need is a source for the
63       master list of all the items, and a list of those already selected. If
64       your dependency heirachy doesn't require the concept of items that are
65       already selected, simply don't pass anything to the constructor for it.
66
67       Please note that the class Algorithm::Dependency does NOT implement an
68       ordering, for speed and simplicity reasons. That is, the "schedule" it
69       provides is not in any particular order. If item 'A' depends on item
70       'B', it will not place B before A in the schedule. This makes it
71       unsuitable for things like software installers, as they typically would
72       need B to be installed before A, or the installation of A would fail.
73
74       For dependency heirachies requiring the items to be acted on in a
75       particular order, either top down or bottom up, see
76       Algorithm::Dependency::Ordered.  It should be more applicable for your
77       needs. This is the the subclass you would probably use to implement a
78       simple ( non-versioned ) package installation system. Please note that
79       an ordered heirachy has additional constraints. For example, circular
80       dependencies ARE legal in a non-ordered heirachy, but ARE NOT legal in
81       an ordered heirachy.
82
83   Extending
84       A module for creating a source from a simple flat file is included. For
85       details see Algorithm::Dependency::Source::File. Information on
86       creating a source for your particular use is in
87       Algorithm::Dependency::Source.
88

METHODS

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

TO DO

178       Add the "check_source" method, to verify the integrity of the source.
179
180       Possibly add Algorithm::Dependency::Versions, to implement an ordered
181       dependency tree with versions, like for perl modules.
182
183       Currently readonly. Make the whole thing writable, so the module can be
184       used as the core of an actual dependency application, as opposed to
185       just being a tool.
186

SUPPORT

188       Bugs should be submitted via the CPAN bug tracker, located at
189
190       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Dependency>
191
192       For general comments, contact the author.
193

AUTHOR

195       Adam Kennedy <adamk@cpan.org>
196

SEE ALSO

198       Algorithm::Dependency::Ordered, Algorithm::Dependency::Item,
199       Algorithm::Dependency::Source, Algorithm::Dependency::Source::File
200
202       Copyright 2003 - 2009 Adam Kennedy.
203
204       This program is free software; you can redistribute it and/or modify it
205       under the same terms as Perl itself.
206
207       The full text of the license can be found in the LICENSE file included
208       with this module.
209
210
211
212perl v5.28.0                      2009-04-14          Algorithm::Dependency(3)
Impressum