CPANPLUS::Backend(3pm)

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

NAME

6       CPANPLUS::Backend - programmer's interface to CPANPLUS
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.pm
191       Text-Bastardize-1.06
192       AYRNIEU/Text-Bastardize
193       AYRNIEU/Text-Bastardize-1.06
194       AYRNIEU/Text-Bastardize-1.06.tar.gz
195       http://example.com/Text-Bastardize-1.06.tar.gz
196       file:///tmp/Text-Bastardize-1.06.tar.gz
197       /tmp/Text-Bastardize-1.06
198       ./Text-Bastardize-1.06
199       .
200
201       These items would all come up with a "CPANPLUS::Module" object for
202       "Text::Bastardize". The ones marked explicitly as being version 1.06
203       would give back a "CPANPLUS::Module" object of that version.  Even if
204       the version on CPAN is currently higher.
205
206       The last three are examples of PATH resolution. In the first, we supply
207       an absolute path to the unwrapped distribution. In the second the
208       distribution is relative to the current working directory.  In the
209       third, we will use the current working directory.
210
211       If "parse_module" is unable to actually find the module you are looking
212       for in its module tree, but you supplied it with an author, module and
213       version part in a distribution name or URI, it will create a fake
214       "CPANPLUS::Module" object for you, that you can use just like the real
215       thing.
216
217       See CPANPLUS::Module for the operations you can perform on a module
218       object.
219
220       If even this fancy guessing doesn't enable "parse_module" to create a
221       fake module object for you to use, it will warn about an error and
222       return false.
223
224   $bool = $cb->reload_indices( [update_source => BOOL, verbose => BOOL] );
225       This method reloads the source files.
226
227       If "update_source" is set to true, this will fetch new source files
228       from your CPAN mirror. Otherwise, "reload_indices" will do its usual
229       cache checking and only update them if they are out of date.
230
231       By default, "update_source" will be false.
232
233       The verbose setting defaults to what you have specified in your config
234       file.
235
236       Returns true on success and false on failure.
237
238   $bool = $cb->flush(CACHE_NAME)
239       This method allows flushing of caches.  There are several things which
240       can be flushed:
241
242       •   "methods"
243
244           The return status of methods which have been attempted, such as
245           different ways of fetching files.  It is recommended that automatic
246           flushing be used instead.
247
248       •   "hosts"
249
250           The return status of URIs which have been attempted, such as
251           different hosts of fetching files.  It is recommended that
252           automatic flushing be used instead.
253
254       •   "modules"
255
256           Information about modules such as prerequisites and whether
257           installation succeeded, failed, or was not attempted.
258
259       •   "lib"
260
261           This resets PERL5LIB, which is changed to ensure that while
262           installing modules they are in our @INC.
263
264       •   "load"
265
266           This resets the cache of modules we've attempted to load, but
267           failed.  This enables you to load them again after a failed load,
268           if they somehow have become available.
269
270       •   "all"
271
272           Flush all of the aforementioned caches.
273
274       Returns true on success and false on failure.
275
276   @mods = $cb->installed()
277       Returns a list of module objects of all your installed modules.  If an
278       error occurs, it will return false.
279
280       See CPANPLUS::Module for the operations you can perform on a module
281       object.
282
283   $bool = $cb->local_mirror([path => '/dir/to/save/to', index_files => BOOL,
284       force => BOOL, verbose => BOOL] )
285       Creates a local mirror of CPAN, of only the most recent sources in a
286       location you specify. If you set this location equal to a custom host
287       in your "CPANPLUS::Config" you can use your local mirror to install
288       from.
289
290       It takes the following arguments:
291
292       path
293           The location where to create the local mirror.
294
295       index_files
296           Enable/disable fetching of index files. You can disable fetching of
297           the index files if you don't plan to use the local mirror as your
298           primary site, or if you'd like up-to-date index files be fetched
299           from elsewhere.
300
301           Defaults to true.
302
303       force
304           Forces refetching of packages, even if they are there already.
305
306           Defaults to whatever setting you have in your "CPANPLUS::Config".
307
308       verbose
309           Prints more messages about what its doing.
310
311           Defaults to whatever setting you have in your "CPANPLUS::Config".
312
313       Returns true on success and false on error.
314
315   $file = $cb->autobundle([path => OUTPUT_PATH, force => BOOL, verbose =>
316       BOOL])
317       Writes out a snapshot of your current installation in "CPAN" bundle
318       style. This can then be used to install the same modules for a
319       different or on a different machine by issuing the following commands:
320
321           ### using the default shell:
322           CPAN Terminal> i file://path/to/Snapshot_XXYY.pm
323
324           ### using the API
325           $modobj = $cb->parse_module( module => 'file://path/to/Snapshot_XXYY.pm' );
326           $modobj->install;
327
328       It will, by default, write to an 'autobundle' directory under your
329       cpanplus home directory, but you can override that by supplying a
330       "path" argument.
331
332       It will return the location of the output file on success and false on
333       failure.
334
335   $bool = $cb->save_state
336       Explicit command to save memory state to disk. This can be used to save
337       information to disk about where a module was extracted, the result of
338       "make test", etc. This will then be re-loaded into memory when a new
339       session starts.
340
341       The capability of saving state to disk depends on the source engine
342       being used (See "CPANPLUS::Config" for the option to choose your source
343       engine). The default storage engine supports this option.
344
345       Most users will not need this command, but it can handy for automated
346       systems like setting up CPAN smoke testers.
347
348       The method will return true if it managed to save the state to disk, or
349       false if it did not.
350

CUSTOM MODULE SOURCES

352       Besides the sources as provided by the general "CPAN" mirrors, it's
353       possible to add your own sources list to your "CPANPLUS" index.
354
355       The methodology behind this works much like "Debian's apt-sources".
356
357       The methods below show you how to make use of this functionality. Also
358       note that most of these methods are available through the default shell
359       plugin command "/cs", making them available as shortcuts through the
360       shell and via the command line.
361
362   %files = $cb->list_custom_sources
363       Returns a mapping of registered custom sources and their local indices
364       as follows:
365
366           /full/path/to/local/index => http://remote/source
367
368       Note that any file starting with an "#" is being ignored.
369
370   $local_index = $cb->add_custom_source( uri => URI, [verbose => BOOL] );
371       Adds an "URI" to your own sources list and mirrors its index. See the
372       documentation on "$cb->update_custom_source" on how this is done.
373
374       Returns the full path to the local index on success, or false on
375       failure.
376
377       Note that when adding a new "URI", the change to the in-memory tree is
378       not saved until you rebuild or save the tree to disk again. You can do
379       this using the "$cb->reload_indices" method.
380
381   $local_index = $cb->remove_custom_source( uri => URI, [verbose => BOOL] );
382       Removes an "URI" from your own sources list and removes its index.
383
384       To find out what "URI"s you have as part of your own sources list, use
385       the "$cb->list_custom_sources" method.
386
387       Returns the full path to the deleted local index file on success, or
388       false on failure.
389
390   $bool = $cb->update_custom_source( [remote => URI] );
391       Updates the indexes for all your custom sources. It does this by
392       fetching a file called "packages.txt" in the root of the custom
393       sources' "URI".  If you provide the "remote" argument, it will only
394       update the index for that specific "URI".
395
396       Here's an example of how custom sources would resolve into index files:
397
398         file:///path/to/sources       =>  file:///path/to/sources/packages.txt
399         http://example.com/sources    =>  http://example.com/sources/packages.txt
400         ftp://example.com/sources     =>  ftp://example.com/sources/packages.txt
401
402       The file "packages.txt" simply holds a list of packages that can be
403       found under the root of the "URI". This file can be automatically
404       generated for you when the remote source is a "file:// URI". For
405       "http://", "ftp://", and similar, the administrator of that repository
406       should run the method "$cb->write_custom_source_index" on the
407       repository to allow remote users to index it.
408
409       For details, see the "$cb->write_custom_source_index" method below.
410
411       All packages that are added via this mechanism will be attributed to
412       the author with "CPANID" "LOCAL". You can use this id to search for all
413       added packages.
414
415   $file = $cb->write_custom_source_index( path => /path/to/package/root, [to
416       => /path/to/index/file, verbose => BOOL] );
417       Writes the index for a custom repository root. Most users will not have
418       to worry about this, but administrators of a repository will need to
419       make sure their indexes are up to date.
420
421       The index will be written to a file called "packages.txt" in your
422       repository root, which you can specify with the "path" argument. You
423       can override this location by specifying the "to" argument, but in
424       normal operation, that should not be required.
425
426       Once the index file is written, users can then add the "URI" pointing
427       to the repository to their custom list of sources and start using it
428       right away. See the "$cb->add_custom_source" method for user details.
429

BUG REPORTS

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

AUTHOR

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

COPYRIGHT

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