Indexer/Tutorial.pm

filter: Statementstmt 100% 11 / 11 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 100% 14 / 14 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« BackPANstats.pm ↑ Summary Indexer/Worker/JustShowDist.pm »
1 package MyCPAN::Indexer::Tutorial;
2 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 $VERSION = '1.282';
7  
8 =encoding utf8
9  
10 =head1 NAME
11  
12 MyCPAN::Indexer::Tutorial - How the backpan_indexer.pl pieces fit together
13  
14 =head1 DESCRIPTION
15  
16 The C<MyCPAN::Indexer> system lets you plug in different components to
17 control major portions of the process of examining Perl distributions
18 and collating the results. It's up to each component to obey its
19 interface and do that parts the other components expect it to do. The
20 idea is to decouple some of these bits as much as possible.
21  
22 As C<backpan_indexer.pl> does its work, it stores information about
23 its components in an anonymous hash called C<notes>. The different
24 components have access to this hash. (To Do: this is some pretty bad
25 design smell, but that's how it is right now).
26  
27 Specific implementations will impose other requirements not listed
28 in this tutorial.
29  
30 =head1 The Application
31  
32 The application is the bit that you write when you want to do
33 something very specialized with a different process. The application
34 object controls the environment, setting up the configuration, and other
35 application-level type things.
36  
37 See C<MyCPAN::Indexer::App::BackPAN>, the module version, and
38 C<backpan_indexer.pl>, the script version.
39  
40 =head1 The Coordinator
41  
42 The coordinator is just a way for the components to talk to each
43 other. The application starts up, creates a coordinator object, and
44 stores it. The application gives a reference to the coordinator to
45 every component.
46  
47 When the application creates components, it tells each about the
48 coordinator. Each component can talk to the coordinator to get to
49 parts of the application it doesn't directly know about. Each
50 component tells the coordinator about itself so the coordinator can
51 talk to any component.
52  
53 The coordinator also maintains the "notes", which are arbitrary bits
54 of information that components use to pass information around. The
55 notes are like a scratch pad where components can leave information
56 for other components.
57  
58 See C<MyCPAN::Indexer::Coordinator>.
59  
60 =head1 Components
61  
62 =head1 The Indexer class
63  
64 Most of the work to examine a Perl distribution is in
65 C<MyCPAN::Indexer>. When it gets down to it, everything C<MyCPAN>
66 knows about Perl distributions is in there. It has a C<run()> method
67 which handles the examination. It kicks off C<examine>, which figures
68 out what to do by getting a list of steps from C<examine_dist_steps>.
69  
70 This technique is common throughout C<MyCPAN::Indexer>. One method
71 returns a list of methods to run. This way, a subclass can control the
72 process by overriding the method that returns the steps.
73  
74 The basic class is C<MyCPAN::Indexer>, but
75 C<MyCPAN::Indexer::TestCensus> is an example of another indexing
76 class.
77  
78 Implements:
79  
80 get_indexer()
81  
82 Creates in C<notes>:
83  
84 indexer_callback - a sub reference that wraps its run routine
85  
86 Expects in C<notes>:
87  
88 nothing
89  
90 =head2 The Queue class
91  
92 The Queue class is responsible for getting the list of distributions to
93 process.
94  
95 C<backpan_indexer.pl> calls C<get_queue> and passes it a ConfigReader::Simple
96 object. C<get_queue> does whatever it needs to do, then returns an array
97 reference of file paths to process. Each path should represent a single
98 Perl distribution.
99  
100 Implements:
101  
102 get_queue()
103  
104 Creates in C<notes>:
105  
106 queue - a reference to the array reference returned by get_queue.
107  
108 Expects in C<notes>:
109  
110 nothing
111  
112 To Do: The Queue class should really be an iterator of some sort. Instead
113 of returning an array (which it can't change), return an iterator.
114  
115 =head2 The Worker class
116  
117 The Worker class returns the anonymous subroutine that the interface
118 class calls for each of its cycles. Inside that code reference, do the
119 actual indexing work, including saving the results.
120 C<backpan_indexer.pl> calls C<get_task> with a reference to its
121 C<notes> hash.
122  
123 Implements:
124  
125 get_task()
126  
127 Creates in C<notes>
128  
129 child_task - a reference to the code reference returned by get_task.
130  
131 Expects in C<notes>
132  
133 nothing
134  
135 To Do: There should be a storage class which the worker class hands
136 the results to.
137  
138 =head2 The Reporter class
139  
140 The Reporter class implements the bits to store the result of the
141 Worker class. C<backpan_indexer.pl> calls C<get_reporter> with a
142 reference to its C<notes> hash.
143  
144 Implements:
145  
146 get_reporter( $info )
147  
148 Creates in C<notes>:
149  
150 reporter - the code ref to handle storing the information
151  
152 Expects in C<notes>:
153  
154 nothing
155  
156 Expects in config:
157  
158 nothing
159  
160 =head2 The Dispatcher class
161  
162 The Dispatcher class implements the bits to hand out work to the
163 worker class. The Interface class, discussed next, repeatedly calls
164 the interface_callback code ref the Dispatcher class provides.
165  
166 Implements:
167  
168 get_dispatcher()
169  
170 Creates in C<notes>
171  
172 dispatcher - the dispatcher object, with start and finish methods
173 interface_callback - a code ref to call repeatedly in the Interface class
174  
175 Expects in C<notes>
176  
177 child_task - the code ref that handles indexing a single dist
178 queue - the array ref of dist paths
179  
180 =head2 The Collator class
181  
182 After the Dispatcher class finishes its queue of work, the Collator class
183 comes in and does something with the collection of reports.
184  
185 Implements:
186  
187 get_collator()
188  
189 Creates in C<notes>
190  
191 collator - a subroutine reference
192  
193 Expects in C<notes>
194  
195 nothing
196  
197 =head2 The Interface class
198  
199 The Interface class really has two jobs. It makes the live reporting
200 interface while C<backpan_indexer.pl> runs, at it repeatedly calls
201 the dispatcher to start new work.
202  
203 Implements:
204  
205 do_interface()
206  
207 Creates in C<notes>:
208  
209 nothing
210  
211 Expects in C<notes>
212  
213 interface_callback - a code ref to call repeatedly in the Interface class
214  
215 =head1 SEE ALSO
216  
217 MyCPAN::Indexer
218  
219 =head1 SOURCE AVAILABILITY
220  
221 This code is in Github:
222  
223 git://github.com/briandfoy/mycpan-indexer.git
224  
225 =head1 AUTHOR
226  
227 brian d foy, C<< <bdfoy@cpan.org> >>
228  
229 =head1 COPYRIGHT AND LICENSE
230  
231 Copyright © 2008-2018, brian d foy <bdfoy@cpan.org>. All rights reserved.
232  
233 You may redistribute this under the terms of the Artistic License 2.0.
234  
235 =cut
236  
237 1 1;
« BackPANstats.pm ↑ Summary Indexer/Worker/JustShowDist.pm »