CPANPLUS::Backend(3pm)

1CPANPLUS::Backend(3pm) Perl Programmers Reference Guide CPANPLUS::Backend(3pm)
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
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

METHODS

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

CUSTOM MODULE SOURCES

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

BUG REPORTS

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

AUTHOR

433       This module by Jos Boumans <kane@cpan.org>.
434

COPYRIGHT

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