1CPANPLUS::Backend(3pm) Perl Programmers Reference Guide CPANPLUS::Backend(3pm)
2
3
4
6 CPANPLUS::Backend
7
9 my $cb = CPANPLUS::Backend->new;
10 my $conf = $cb->configure_object;
11
12 my $author = $cb->author_tree('KANE');
13 my $mod = $cb->module_tree('Some::Module');
14 my $mod = $cb->parse_module( module => 'Some::Module' );
15
16 my @objs = $cb->search( type => TYPE,
17 allow => [...] );
18
19 $cb->flush('all');
20 $cb->reload_indices;
21 $cb->local_mirror;
22
24 This module provides the programmer's interface to the "CPANPLUS"
25 libraries.
26
28 When "CPANPLUS::Backend" is loaded, which is necessary for just about
29 every <CPANPLUS> operation, the environment variable
30 "PERL5_CPANPLUS_IS_RUNNING" is set to the current process id.
31
32 Additionally, the environment variable "PERL5_CPANPLUS_IS_VERSION" will
33 be set to the version of "CPANPLUS::Backend".
34
35 This information might be useful somehow to spawned processes.
36
38 $cb = CPANPLUS::Backend->new( [CONFIGURE_OBJ] )
39 This method returns a new "CPANPLUS::Backend" object. This also
40 initialises the config corresponding to this object. You have two
41 choices in this:
42
43 Provide a valid "CPANPLUS::Configure" object
44 This will be used verbatim.
45
46 No arguments
47 Your default config will be loaded and used.
48
49 New will return a "CPANPLUS::Backend" object on success and die on
50 failure.
51
52 $href = $cb->module_tree( [@modules_names_list] )
53 Returns a reference to the CPANPLUS module tree.
54
55 If you give it any arguments, they will be treated as module names and
56 "module_tree" will try to look up these module names and return the
57 corresponding module objects instead.
58
59 See CPANPLUS::Module for the operations you can perform on a module
60 object.
61
62 $href = $cb->author_tree( [@author_names_list] )
63 Returns a reference to the CPANPLUS author tree.
64
65 If you give it any arguments, they will be treated as author names and
66 "author_tree" will try to look up these author names and return the
67 corresponding author objects instead.
68
69 See CPANPLUS::Module::Author for the operations you can perform on an
70 author object.
71
72 $conf = $cb->configure_object;
73 Returns a copy of the "CPANPLUS::Configure" object.
74
75 See CPANPLUS::Configure for operations you can perform on a configure
76 object.
77
78 $su = $cb->selfupdate_object;
79 Returns a copy of the "CPANPLUS::Selfupdate" object.
80
81 See the CPANPLUS::Selfupdate manpage for the operations you can perform
82 on the selfupdate object.
83
84 @mods = $cb->search( type => TYPE, allow => AREF, [data => AREF, verbose =>
85 BOOL] )
86 "search" enables you to search for either module or author objects,
87 based on their data. The "type" you can specify is any of the accessors
88 specified in "CPANPLUS::Module::Author" or "CPANPLUS::Module". "search"
89 will determine by the "type" you specified whether to search by author
90 object or module object.
91
92 You have to specify an array reference of regular expressions or
93 strings to match against. The rules used for this array ref are the
94 same as in "Params::Check", so read that manpage for details.
95
96 The search is an "or" search, meaning that if "any" of the criteria
97 match, the search is considered to be successful.
98
99 You can specify the result of a previous search as "data" to limit the
100 new search to these module or author objects, rather than the entire
101 module or author tree. This is how you do "and" searches.
102
103 Returns a list of module or author objects on success and false on
104 failure.
105
106 See CPANPLUS::Module for the operations you can perform on a module
107 object. See CPANPLUS::Module::Author for the operations you can
108 perform on an author object.
109
110 $backend_rv = $cb->fetch( modules => \@mods )
111 Fetches a list of modules. @mods can be a list of distribution names,
112 module names or module objects--basically anything that parse_module
113 can understand.
114
115 See the equivalent method in "CPANPLUS::Module" for details on other
116 options you can pass.
117
118 Since this is a multi-module method call, the return value is
119 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
120 module's documentation on how to interpret the return value.
121
122 $backend_rv = $cb->extract( modules => \@mods )
123 Extracts a list of modules. @mods can be a list of distribution names,
124 module names or module objects--basically anything that parse_module
125 can understand.
126
127 See the equivalent method in "CPANPLUS::Module" for details on other
128 options you can pass.
129
130 Since this is a multi-module method call, the return value is
131 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
132 module's documentation on how to interpret the return value.
133
134 $backend_rv = $cb->install( modules => \@mods )
135 Installs a list of modules. @mods can be a list of distribution names,
136 module names or module objects--basically anything that parse_module
137 can understand.
138
139 See the equivalent method in "CPANPLUS::Module" for details on other
140 options you can pass.
141
142 Since this is a multi-module method call, the return value is
143 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
144 module's documentation on how to interpret the return value.
145
146 $backend_rv = $cb->readme( modules => \@mods )
147 Fetches the readme for a list of modules. @mods can be a list of
148 distribution names, module names or module objects--basically anything
149 that parse_module can understand.
150
151 See the equivalent method in "CPANPLUS::Module" for details on other
152 options you can pass.
153
154 Since this is a multi-module method call, the return value is
155 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
156 module's documentation on how to interpret the return value.
157
158 $backend_rv = $cb->files( modules => \@mods )
159 Returns a list of files used by these modules if they are installed.
160 @mods can be a list of distribution names, module names or module
161 objects--basically anything that parse_module can understand.
162
163 See the equivalent method in "CPANPLUS::Module" for details on other
164 options you can pass.
165
166 Since this is a multi-module method call, the return value is
167 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
168 module's documentation on how to interpret the return value.
169
170 $backend_rv = $cb->distributions( modules => \@mods )
171 Returns a list of module objects representing all releases for this
172 module on success. @mods can be a list of distribution names, module
173 names or module objects, basically anything that parse_module can
174 understand.
175
176 See the equivalent method in "CPANPLUS::Module" for details on other
177 options you can pass.
178
179 Since this is a multi-module method call, the return value is
180 implemented as a "CPANPLUS::Backend::RV" object. Please consult that
181 module's documentation on how to interpret the return value.
182
183 $mod_obj = $cb->parse_module( module => $modname|$distname|$modobj|URI|PATH
184 )
185 "parse_module" tries to find a "CPANPLUS::Module" object that matches
186 your query. Here's a list of examples you could give to "parse_module";
187
188 Text::Bastardize
189 Text-Bastardize
190 Text-Bastardize-1.06
191 AYRNIEU/Text-Bastardize
192 AYRNIEU/Text-Bastardize-1.06
193 AYRNIEU/Text-Bastardize-1.06.tar.gz
194 http://example.com/Text-Bastardize-1.06.tar.gz
195 file:///tmp/Text-Bastardize-1.06.tar.gz
196 /tmp/Text-Bastardize-1.06
197 ./Text-Bastardize-1.06
198 .
199
200 These items would all come up with a "CPANPLUS::Module" object for
201 "Text::Bastardize". The ones marked explicitly as being version 1.06
202 would give back a "CPANPLUS::Module" object of that version. Even if
203 the version on CPAN is currently higher.
204
205 The last three are examples of PATH resolution. In the first, we supply
206 an absolute path to the unwrapped distribution. In the second the
207 distribution is relative to the current working directory. In the
208 third, we will use the current working directory.
209
210 If "parse_module" is unable to actually find the module you are looking
211 for in its module tree, but you supplied it with an author, module and
212 version part in a distribution name or URI, it will create a fake
213 "CPANPLUS::Module" object for you, that you can use just like the real
214 thing.
215
216 See CPANPLUS::Module for the operations you can perform on a module
217 object.
218
219 If even this fancy guessing doesn't enable "parse_module" to create a
220 fake module object for you to use, it will warn about an error and
221 return false.
222
223 $bool = $cb->reload_indices( [update_source => BOOL, verbose => BOOL] );
224 This method reloads the source files.
225
226 If "update_source" is set to true, this will fetch new source files
227 from your CPAN mirror. Otherwise, "reload_indices" will do its usual
228 cache checking and only update them if they are out of date.
229
230 By default, "update_source" will be false.
231
232 The verbose setting defaults to what you have specified in your config
233 file.
234
235 Returns true on success and false on failure.
236
237 $bool = $cb->flush(CACHE_NAME)
238 This method allows flushing of caches. There are several things which
239 can be flushed:
240
241 · "methods"
242
243 The return status of methods which have been attempted, such as
244 different ways of fetching files. It is recommended that automatic
245 flushing be used instead.
246
247 · "hosts"
248
249 The return status of URIs which have been attempted, such as
250 different hosts of fetching files. It is recommended that
251 automatic flushing be used instead.
252
253 · "modules"
254
255 Information about modules such as prerequisites and whether
256 installation succeeded, failed, or was not attempted.
257
258 · "lib"
259
260 This resets PERL5LIB, which is changed to ensure that while
261 installing modules they are in our @INC.
262
263 · "load"
264
265 This resets the cache of modules we've attempted to load, but
266 failed. This enables you to load them again after a failed load,
267 if they somehow have become available.
268
269 · "all"
270
271 Flush all of the aforementioned caches.
272
273 Returns true on success and false on failure.
274
275 @mods = $cb->installed()
276 Returns a list of module objects of all your installed modules. If an
277 error occurs, it will return false.
278
279 See CPANPLUS::Module for the operations you can perform on a module
280 object.
281
282 $bool = $cb->local_mirror([path => '/dir/to/save/to', index_files => BOOL,
283 force => BOOL, verbose => BOOL] )
284 Creates a local mirror of CPAN, of only the most recent sources in a
285 location you specify. If you set this location equal to a custom host
286 in your "CPANPLUS::Config" you can use your local mirror to install
287 from.
288
289 It takes the following arguments:
290
291 path
292 The location where to create the local mirror.
293
294 index_files
295 Enable/disable fetching of index files. You can disable fetching of
296 the index files if you don't plan to use the local mirror as your
297 primary site, or if you'd like up-to-date index files be fetched
298 from elsewhere.
299
300 Defaults to true.
301
302 force
303 Forces refetching of packages, even if they are there already.
304
305 Defaults to whatever setting you have in your "CPANPLUS::Config".
306
307 verbose
308 Prints more messages about what its doing.
309
310 Defaults to whatever setting you have in your "CPANPLUS::Config".
311
312 Returns true on success and false on error.
313
314 $file = $cb->autobundle([path => OUTPUT_PATH, force => BOOL, verbose =>
315 BOOL])
316 Writes out a snapshot of your current installation in "CPAN" bundle
317 style. This can then be used to install the same modules for a
318 different or on a different machine by issuing the following commands:
319
320 ### using the default shell:
321 CPAN Terminal> i file://path/to/Snapshot_XXYY.pm
322
323 ### using the API
324 $modobj = $cb->parse_module( module => 'file://path/to/Snapshot_XXYY.pm' );
325 $modobj->install;
326
327 It will, by default, write to an 'autobundle' directory under your
328 cpanplus homedirectory, but you can override that by supplying a "path"
329 argument.
330
331 It will return the location of the output file on success and false on
332 failure.
333
334 $bool = $cb->save_state
335 Explicit command to save memory state to disk. This can be used to save
336 information to disk about where a module was extracted, the result of
337 "make test", etc. This will then be re-loaded into memory when a new
338 session starts.
339
340 The capability of saving state to disk depends on the source engine
341 being used (See "CPANPLUS::Config" for the option to choose your source
342 engine). The default storage engine supports this option.
343
344 Most users will not need this command, but it can handy for automated
345 systems like setting up CPAN smoke testers.
346
347 The method will return true if it managed to save the state to disk, or
348 false if it did not.
349
351 Besides the sources as provided by the general "CPAN" mirrors, it's
352 possible to add your own sources list to your "CPANPLUS" index.
353
354 The methodology behind this works much like "Debian's apt-sources".
355
356 The methods below show you how to make use of this functionality. Also
357 note that most of these methods are available through the default shell
358 plugin command "/cs", making them available as shortcuts through the
359 shell and via the commandline.
360
361 %files = $cb->list_custom_sources
362 Returns a mapping of registered custom sources and their local indices
363 as follows:
364
365 /full/path/to/local/index => http://remote/source
366
367 Note that any file starting with an "#" is being ignored.
368
369 $local_index = $cb->add_custom_source( uri => URI, [verbose => BOOL] );
370 Adds an "URI" to your own sources list and mirrors its index. See the
371 documentation on "$cb->update_custom_source" on how this is done.
372
373 Returns the full path to the local index on success, or false on
374 failure.
375
376 Note that when adding a new "URI", the change to the in-memory tree is
377 not saved until you rebuild or save the tree to disk again. You can do
378 this using the "$cb->reload_indices" method.
379
380 $local_index = $cb->remove_custom_source( uri => URI, [verbose => BOOL] );
381 Removes an "URI" from your own sources list and removes its index.
382
383 To find out what "URI"s you have as part of your own sources list, use
384 the "$cb->list_custom_sources" method.
385
386 Returns the full path to the deleted local index file on success, or
387 false on failure.
388
389 $bool = $cb->update_custom_source( [remote => URI] );
390 Updates the indexes for all your custom sources. It does this by
391 fetching a file called "packages.txt" in the root of the custom
392 sources's "URI". If you provide the "remote" argument, it will only
393 update the index for that specific "URI".
394
395 Here's an example of how custom sources would resolve into index files:
396
397 file:///path/to/sources => file:///path/to/sources/packages.txt
398 http://example.com/sources => http://example.com/sources/packages.txt
399 ftp://example.com/sources => ftp://example.com/sources/packages.txt
400
401 The file "packages.txt" simply holds a list of packages that can be
402 found under the root of the "URI". This file can be automatically
403 generated for you when the remote source is a "file:// URI". For
404 "http://", "ftp://", and similar, the administrator of that repository
405 should run the method "$cb->write_custom_source_index" on the
406 repository to allow remote users to index it.
407
408 For details, see the "$cb->write_custom_source_index" method below.
409
410 All packages that are added via this mechanism will be attributed to
411 the author with "CPANID" "LOCAL". You can use this id to search for all
412 added packages.
413
414 $file = $cb->write_custom_source_index( path => /path/to/package/root, [to
415 => /path/to/index/file, verbose => BOOL] );
416 Writes the index for a custom repository root. Most users will not have
417 to worry about this, but administrators of a repository will need to
418 make sure their indexes are up to date.
419
420 The index will be written to a file called "packages.txt" in your
421 repository root, which you can specify with the "path" argument. You
422 can override this location by specifying the "to" argument, but in
423 normal operation, that should not be required.
424
425 Once the index file is written, users can then add the "URI" pointing
426 to the repository to their custom list of sources and start using it
427 right away. See the "$cb->add_custom_source" method for user details.
428
430 Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>.
431
433 This module by Jos Boumans <kane@cpan.org>.
434
436 The CPAN++ interface (of which this module is a part of) is copyright
437 (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.
438
439 This library is free software; you may redistribute and/or modify it
440 under the same terms as Perl itself.
441
443 CPANPLUS::Configure, CPANPLUS::Module, CPANPLUS::Module::Author,
444 CPANPLUS::Selfupdate
445
446
447
448perl v5.12.4 2011-06-07 CPANPLUS::Backend(3pm)