CPANPLUS::Backend(3pm)

1CPANPLUS::Backend(3)  User Contributed Perl Documentation CPANPLUS::Backend(3)
2
3
4

NAME

6       CPANPLUS::Backend
7

SYNOPSIS

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

DESCRIPTION

24       This module provides the programmer's interface to the "CPANPLUS"
25       libraries.
26

ENVIRONMENT

28       When "CPANPLUS::Backend" is loaded, which is necessary for just about
29       every <CPANPLUS> operation, the environment variable "PERL5_CPAN‐
30       PLUS_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

METHODS

38       $cb = CPANPLUS::Backend->new( [CONFIGURE_OBJ] )
39
40       This method returns a new "CPANPLUS::Backend" object.  This also ini‐
41       tialises the config corresponding to this object.  You have two choices
42       in this:
43
44       Provide a valid "CPANPLUS::Configure" object
45           This will be used verbatim.
46
47       No arguments
48           Your default config will be loaded and used.
49
50       New will return a "CPANPLUS::Backend" object on success and die on
51       failure.
52
53       $href = $cb->module_tree( [@modules_names_list] )
54
55       Returns a reference to the CPANPLUS module tree.
56
57       If you give it any arguments, they will be treated as module names and
58       "module_tree" will try to look up these module names and return the
59       corresponding module objects instead.
60
61       See CPANPLUS::Module for the operations you can perform on a module
62       object.
63
64       $href = $cb->author_tree( [@author_names_list] )
65
66       Returns a reference to the CPANPLUS author tree.
67
68       If you give it any arguments, they will be treated as author names and
69       "author_tree" will try to look up these author names and return the
70       corresponding author objects instead.
71
72       See CPANPLUS::Module::Author for the operations you can perform on an
73       author object.
74
75       $conf = $cb->configure_object ()
76
77       Returns a copy of the "CPANPLUS::Configure" object.
78
79       See CPANPLUS::Configure for operations you can perform on a configure
80       object.
81
82       $su = $cb->selfupdate_object;
83
84       Returns a copy of the "CPANPLUS::Selfupdate" object.
85
86       See the CPANPLUS::Selfupdate manpage for the operations you can perform
87       on the selfupdate object.
88
89       @mods = $cb->search( type => TYPE, allow => AREF, [data => AREF, ver‐
90       bose => BOOL] )
91
92       "search" enables you to search for either module or author objects,
93       based on their data. The "type" you can specify is any of the accessors
94       specified in "CPANPLUS::Module::Author" or "CPANPLUS::Module". "search"
95       will determine by the "type" you specified whether to search by author
96       object or module object.
97
98       You have to specify an array reference of regular expressions or
99       strings to match against. The rules used for this array ref are the
100       same as in "Params::Check", so read that manpage for details.
101
102       The search is an "or" search, meaning that if "any" of the criteria
103       match, the search is considered to be successful.
104
105       You can specify the result of a previous search as "data" to limit the
106       new search to these module or author objects, rather than the entire
107       module or author tree.  This is how you do "and" searches.
108
109       Returns a list of module or author objects on success and false on
110       failure.
111
112       See CPANPLUS::Module for the operations you can perform on a module
113       object.  See CPANPLUS::Module::Author for the operations you can per‐
114       form on an author object.
115
116       $backend_rv = $cb->fetch( modules => \@mods )
117
118       Fetches a list of modules. @mods can be a list of distribution names,
119       module names or module objects--basically anything that parse_module
120       can understand.
121
122       See the equivalent method in "CPANPLUS::Module" for details on other
123       options you can pass.
124
125       Since this is a multi-module method call, the return value is imple‐
126       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
127       ule's documentation on how to interpret the return value.
128
129       $backend_rv = $cb->extract( modules => \@mods )
130
131       Extracts a list of modules. @mods can be a list of distribution names,
132       module names or module objects--basically anything that parse_module
133       can understand.
134
135       See the equivalent method in "CPANPLUS::Module" for details on other
136       options you can pass.
137
138       Since this is a multi-module method call, the return value is imple‐
139       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
140       ule's documentation on how to interpret the return value.
141
142       $backend_rv = $cb->install( modules => \@mods )
143
144       Installs a list of modules. @mods can be a list of distribution names,
145       module names or module objects--basically anything that parse_module
146       can understand.
147
148       See the equivalent method in "CPANPLUS::Module" for details on other
149       options you can pass.
150
151       Since this is a multi-module method call, the return value is imple‐
152       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
153       ule's documentation on how to interpret the return value.
154
155       $backend_rv = $cb->readme( modules => \@mods )
156
157       Fetches the readme for a list of modules. @mods can be a list of dis‐
158       tribution names, module names or module objects--basically anything
159       that parse_module can understand.
160
161       See the equivalent method in "CPANPLUS::Module" for details on other
162       options you can pass.
163
164       Since this is a multi-module method call, the return value is imple‐
165       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
166       ule's documentation on how to interpret the return value.
167
168       $backend_rv = $cb->files( modules => \@mods )
169
170       Returns a list of files used by these modules if they are installed.
171       @mods can be a list of distribution names, module names or module
172       objects--basically anything that parse_module can understand.
173
174       See the equivalent method in "CPANPLUS::Module" for details on other
175       options you can pass.
176
177       Since this is a multi-module method call, the return value is imple‐
178       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
179       ule's documentation on how to interpret the return value.
180
181       $backend_rv = $cb->distributions( modules => \@mods )
182
183       Returns a list of module objects representing all releases for this
184       module on success.  @mods can be a list of distribution names, module
185       names or module objects, basically anything that parse_module can
186       understand.
187
188       See the equivalent method in "CPANPLUS::Module" for details on other
189       options you can pass.
190
191       Since this is a multi-module method call, the return value is imple‐
192       mented as a "CPANPLUS::Backend::RV" object. Please consult that mod‐
193       ule's documentation on how to interpret the return value.
194
195       $mod_obj = $cb->parse_module( module => $modname⎪$distname⎪$modobj )
196
197       "parse_module" tries to find a "CPANPLUS::Module" object that matches
198       your query. Here's a list of examples you could give to "parse_module";
199
200       Text::Bastardize
201       Text-Bastardize
202       Text-Bastardize-1.06
203       AYRNIEU/Text-Bastardize
204       AYRNIEU/Text-Bastardize-1.06
205       AYRNIEU/Text-Bastardize-1.06.tar.gz
206       http://example.com/Text-Bastardize-1.06.tar.gz
207       file:///tmp/Text-Bastardize-1.06.tar.gz
208
209       These items would all come up with a "CPANPLUS::Module" object for
210       "Text::Bastardize". The ones marked explicitly as being version 1.06
211       would give back a "CPANPLUS::Module" object of that version.  Even if
212       the version on CPAN is currently higher.
213
214       If "parse_module" is unable to actually find the module you are looking
215       for in its module tree, but you supplied it with an author, module and
216       version part in a distribution name or URI, it will create a fake
217       "CPANPLUS::Module" object for you, that you can use just like the real
218       thing.
219
220       See CPANPLUS::Module for the operations you can perform on a module
221       object.
222
223       If even this fancy guessing doesn't enable "parse_module" to create a
224       fake module object for you to use, it will warn about an error and
225       return false.
226
227       $bool = $cb->reload_indices( [update_source => BOOL, verbose => BOOL]
228       );
229
230       This method reloads the source files.
231
232       If "update_source" is set to true, this will fetch new source files
233       from your CPAN mirror. Otherwise, "reload_indices" will do its usual
234       cache checking and only update them if they are out of date.
235
236       By default, "update_source" will be false.
237
238       The verbose setting defaults to what you have specified in your config
239       file.
240
241       Returns true on success and false on failure.
242
243       $bool = $cb->flush(CACHE_NAME)
244
245       This method allows flushing of caches.  There are several things which
246       can be flushed:
247
248       * "methods"
249           The return status of methods which have been attempted, such as
250           different ways of fetching files.  It is recommended that automatic
251           flushing be used instead.
252
253       * "hosts"
254           The return status of URIs which have been attempted, such as dif‐
255           ferent hosts of fetching files.  It is recommended that automatic
256           flushing be used instead.
257
258       * "modules"
259           Information about modules such as prerequisites and whether instal‐
260           lation succeeded, failed, or was not attempted.
261
262       * "lib"
263           This resets PERL5LIB, which is changed to ensure that while
264           installing modules they are in our @INC.
265
266       * "load"
267           This resets the cache of modules we've attempted to load, but
268           failed.  This enables you to load them again after a failed load,
269           if they somehow have become available.
270
271       * "all"
272           Flush all of the aforementioned caches.
273
274       Returns true on success and false on failure.
275
276       @mods = $cb->installed()
277
278       Returns a list of module objects of all your installed modules.  If an
279       error occurs, it will return false.
280
281       See CPANPLUS::Module for the operations you can perform on a module
282       object.
283
284       $bool = $cb->local_mirror([path => '/dir/to/save/to', index_files =>
285       BOOL, force => BOOL, verbose => BOOL] )
286
287       Creates a local mirror of CPAN, of only the most recent sources in a
288       location you specify. If you set this location equal to a custom host
289       in your "CPANPLUS::Config" you can use your local mirror to install
290       from.
291
292       It takes the following arguments:
293
294       path
295           The location where to create the local mirror.
296
297       index_files
298           Enable/disable fetching of index files. This is ok if you don't
299           plan to use the local mirror as your primary sites, or if you'd
300           like up-to-date index files be fetched from elsewhere.
301
302           Defaults to true.
303
304       force
305           Forces refetching of packages, even if they are there already.
306
307           Defaults to whatever setting you have in your "CPANPLUS::Config".
308
309       verbose
310           Prints more messages about what its doing.
311
312           Defaults to whatever setting you have in your "CPANPLUS::Config".
313
314       Returns true on success and false on error.
315
316       $file = $cb->autobundle([path => OUTPUT_PATH, force => BOOL, verbose =>
317       BOOL])
318
319       Writes out a snapshot of your current installation in "CPAN" bundle
320       style. This can then be used to install the same modules for a differ‐
321       ent or on a different machine.
322
323       It will, by default, write to an 'autobundle' directory under your
324       cpanplus homedirectory, but you can override that by supplying a "path"
325       argument.
326
327       It will return the location of the output file on success and false on
328       failure.
329

BUG REPORTS

331       Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>.
332

AUTHOR

334       This module by Jos Boumans <kane@cpan.org>.
335

COPYRIGHT

337       The CPAN++ interface (of which this module is a part of) is copyright
338       (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.
339
340       This library is free software; you may redistribute and/or modify it
341       under the same terms as Perl itself.
342