| 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; | |