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

NAME

6       CPANPLUS::Module - CPAN module objects for CPANPLUS
7

SYNOPSIS

9           ### get a module object from the CPANPLUS::Backend object
10           my $mod = $cb->module_tree('Some::Module');
11
12           ### accessors
13           $mod->version;
14           $mod->package;
15
16           ### methods
17           $mod->fetch;
18           $mod->extract;
19           $mod->install;
20

DESCRIPTION

22       "CPANPLUS::Module" creates objects from the information in the source
23       files. These can then be used to query and perform actions on, like
24       fetching or installing.
25
26       These objects should only be created internally. For "fake" objects,
27       there's the "CPANPLUS::Module::Fake" class. To obtain a module object
28       consult the "CPANPLUS::Backend" documentation.
29

CLASS METHODS

31   accessors ()
32       Returns a list of all accessor methods to the object
33

ACCESSORS

35       An objects of this class has the following accessors:
36
37       name
38           Name of the module.
39
40       module
41           Name of the module.
42
43       version
44           Version of the module. Defaults to '0.0' if none was provided.
45
46       path
47           Extended path on the mirror.
48
49       comment
50           Any comment about the module -- largely unused.
51
52       package
53           The name of the package.
54
55       description
56           Description of the module -- only registered modules have this.
57
58       dslip
59           The five character dslip string, that represents meta-data of the
60           module -- again, only registered modules have this.
61
62       status
63           The "CPANPLUS::Module::Status" object associated with this object.
64           (see below).
65
66       author
67           The "CPANPLUS::Module::Author" object associated with this object.
68
69       parent
70           The "CPANPLUS::Internals" object that spawned this module object.
71

STATUS ACCESSORS

73       "CPANPLUS" caches a lot of results from method calls and saves data it
74       collected along the road for later reuse.
75
76       "CPANPLUS" uses this internally, but it is also available for the end
77       user. You can get a status object by calling:
78
79           $modobj->status
80
81       You can then query the object as follows:
82
83       installer_type
84           The installer type used for this distribution. Will be one of
85           'makemaker' or 'build'. This determines whether
86           "CPANPLUS::Dist::MM" or "CPANPLUS::Dist::Build" will be used to
87           build this distribution.
88
89       dist_cpan
90           The dist object used to do the CPAN-side of the installation.
91           Either a "CPANPLUS::Dist::MM" or "CPANPLUS::Dist::Build" object.
92
93       dist
94           The custom dist object used to do the operating specific side of
95           the installation, if you've chosen to use this. For example, if
96           you've chosen to install using the "ports" format, this may be a
97           "CPANPLUS::Dist::Ports" object.
98
99           Undefined if you didn't specify a separate format to install
100           through.
101
102       prereqs | requires
103           A hashref of prereqs this distribution was found to have. Will look
104           something like this:
105
106               { Carp  => 0.01, strict => 0 }
107
108           Might be undefined if the distribution didn't have any
109           prerequisites.
110
111       configure_requires
112           Like prereqs, but these are necessary to be installed before the
113           build process can even begin.
114
115       signature
116           Flag indicating, if a signature check was done, whether it was OK
117           or not.
118
119       extract
120           The directory this distribution was extracted to.
121
122       fetch
123           The location this distribution was fetched to.
124
125       readme
126           The text of this distributions README file.
127
128       uninstall
129           Flag indicating if an uninstall call was done successfully.
130
131       created
132           Flag indicating if the "create" call to your dist object was done
133           successfully.
134
135       installed
136           Flag indicating if the "install" call to your dist object was done
137           successfully.
138
139       checksums
140           The location of this distributions CHECKSUMS file.
141
142       checksum_ok
143           Flag indicating if the checksums check was done successfully.
144
145       checksum_value
146           The checksum value this distribution is expected to have
147

METHODS

149   $self = CPANPLUS::Module->new( OPTIONS )
150       This method returns a "CPANPLUS::Module" object. Normal users should
151       never call this method directly, but instead use the
152       "CPANPLUS::Backend" to obtain module objects.
153
154       This example illustrates a "new()" call with all required arguments:
155
156               CPANPLUS::Module->new(
157                   module  => 'Foo',
158                   path    => 'authors/id/A/AA/AAA',
159                   package => 'Foo-1.0.tgz',
160                   author  => $author_object,
161                   _id     => INTERNALS_OBJECT_ID,
162               );
163
164       Every accessor is also a valid option to pass to "new".
165
166       Returns a module object on success and false on failure.
167
168   $mod->package_name( [$package_string] )
169       Returns the name of the package a module is in. For "Acme::Bleach" that
170       might be "Acme-Bleach".
171
172   $mod->package_version( [$package_string] )
173       Returns the version of the package a module is in. For a module in the
174       package "Acme-Bleach-1.1.tar.gz" this would be 1.1.
175
176   $mod->package_extension( [$package_string] )
177       Returns the suffix added by the compression method of a package a
178       certain module is in. For a module in "Acme-Bleach-1.1.tar.gz", this
179       would be "tar.gz".
180
181   $mod->package_is_perl_core
182       Returns a boolean indicating of the package a particular module is in,
183       is actually a core perl distribution.
184
185   $mod->module_is_supplied_with_perl_core( [version => $]] )
186       Returns a boolean indicating whether "ANY VERSION" of this module was
187       supplied with the current running perl's core package.
188
189   $mod->is_bundle
190       Returns a boolean indicating if the module you are looking at, is
191       actually a bundle. Bundles are identified as modules whose name starts
192       with "Bundle::".
193
194   $mod->is_autobundle;
195       Returns a boolean indicating if the module you are looking at, is
196       actually an autobundle as generated by "$cb->autobundle".
197
198   $mod->is_third_party
199       Returns a boolean indicating whether the package is a known third-party
200       module (i.e. it's not provided by the standard Perl distribution and is
201       not available on the CPAN, but on a third party software provider).
202       See Module::ThirdParty for more details.
203
204   $mod->third_party_information
205       Returns a reference to a hash with more information about a third-party
206       module. See the documentation about "module_information()" in
207       Module::ThirdParty for more details.
208
209   $clone = $self->clone
210       Clones the current module object for tinkering with.  It will have a
211       clean "CPANPLUS::Module::Status" object, as well as a fake
212       "CPANPLUS::Module::Author" object.
213
214   $where = $self->fetch
215       Fetches the module from a CPAN mirror.  Look at
216       CPANPLUS::Internals::Fetch::_fetch() for details on the options you can
217       pass.
218
219   $path = $self->extract
220       Extracts the fetched module.  Look at
221       CPANPLUS::Internals::Extract::_extract() for details on the options you
222       can pass.
223
224   $type = $self->get_installer_type([prefer_makefile => BOOL])
225       Gets the installer type for this module. This may either be "build" or
226       "makemaker". If "Module::Build" is unavailable or no installer type is
227       available, it will fall back to "makemaker". If both are available, it
228       will pick the one indicated by your config, or by the "prefer_makefile"
229       option you can pass to this function.
230
231       Returns the installer type on success, and false on error.
232
233   $dist = $self->dist([target => 'prepare|create', format =>
234       DISTRIBUTION_TYPE, args => {key => val}]);
235       Create a distribution object, ready to be installed.  Distribution type
236       defaults to your config settings
237
238       The optional "args" hashref is passed on to the specific distribution
239       types' "create" method after being dereferenced.
240
241       Returns a distribution object on success, false on failure.
242
243       See "CPANPLUS::Dist" for details.
244
245   $bool = $mod->prepare( )
246       Convenience method around "install()" that prepares a module without
247       actually building it. This is equivalent to invoking "install" with
248       "target" set to "prepare"
249
250       Returns true on success, false on failure.
251
252   $bool = $mod->create( )
253       Convenience method around "install()" that creates a module.  This is
254       equivalent to invoking "install" with "target" set to "create"
255
256       Returns true on success, false on failure.
257
258   $bool = $mod->test( )
259       Convenience wrapper around "install()" that tests a module, without
260       installing it.  It's the equivalent to invoking "install()" with
261       "target" set to "create" and "skiptest" set to 0.
262
263       Returns true on success, false on failure.
264
265   $bool = $self->install([ target => 'init|prepare|create|install', format =>
266       FORMAT_TYPE, extractdir => DIRECTORY, fetchdir => DIRECTORY, prefer_bin
267       => BOOL, force => BOOL, verbose => BOOL, ..... ]);
268       Installs the current module. This includes fetching it and extracting
269       it, if this hasn't been done yet, as well as creating a distribution
270       object for it.
271
272       This means you can pass it more arguments than described above, which
273       will be passed on to the relevant methods as they are called.
274
275       See "CPANPLUS::Internals::Fetch", "CPANPLUS::Internals::Extract" and
276       "CPANPLUS::Dist" for details.
277
278       Returns true on success, false on failure.
279
280   @list = $self->bundle_modules()
281       Returns a list of module objects the Bundle specifies.
282
283       This requires you to have extracted the bundle already, using the
284       "extract()" method.
285
286       Returns false on error.
287
288   $text = $self->readme
289       Fetches the readme belonging to this module and stores it under
290       "$obj->status->readme". Returns the readme as a string on success and
291       returns false on failure.
292
293   $version = $self->installed_version()
294       Returns the currently installed version of this module, if any.
295
296   $where = $self->installed_file()
297       Returns the location of the currently installed file of this module, if
298       any.
299
300   $dir = $self->installed_dir()
301       Returns the directory (or more accurately, the @INC handle) from which
302       this module was loaded, if any.
303
304   $bool = $self->is_uptodate([version => VERSION_NUMBER])
305       Returns a boolean indicating if this module is uptodate or not.
306
307   $href = $self->details()
308       Returns a hashref with key/value pairs offering more information about
309       a particular module. For example, for "Time::HiRes" it might look like
310       this:
311
312           Author                  Jarkko Hietaniemi (jhi@iki.fi)
313           Description             High resolution time, sleep, and alarm
314           Development Stage       Released
315           Installed File          /usr/local/perl/lib/Time/Hires.pm
316           Interface Style         plain Functions, no references used
317           Language Used           C and perl, a C compiler will be needed
318           Package                 Time-HiRes-1.65.tar.gz
319           Public License          Unknown
320           Support Level           Developer
321           Version Installed       1.52
322           Version on CPAN         1.65
323
324   @list = $self->contains()
325       Returns a list of module objects that represent the modules also
326       present in the package of this module.
327
328       For example, for "Archive::Tar" this might return:
329
330           Archive::Tar
331           Archive::Tar::Constant
332           Archive::Tar::File
333
334   @list_of_hrefs = $self->fetch_report()
335       This function queries the CPAN testers database at
336       http://testers.cpan.org/ for test results of specified module objects,
337       module names or distributions.
338
339       Look at CPANPLUS::Internals::Report::_query_report() for details on the
340       options you can pass and the return value to expect.
341
342   $bool = $self->uninstall([type => [all|man|prog])
343       This function uninstalls the specified module object.
344
345       You can install 2 types of files, either "man" pages or "prog"ram
346       files. Alternately you can specify "all" to uninstall both (which is
347       the default).
348
349       Returns true on success and false on failure.
350
351       Do note that this does an uninstall via the so-called ".packlist", so
352       if you used a module installer like say, "ports" or "apt", you should
353       not use this, but use your package manager instead.
354
355   @modobj = $self->distributions()
356       Returns a list of module objects representing all releases for this
357       module on success, false on failure.
358
359   @list = $self->files ()
360       Returns a list of files used by this module, if it is installed.
361
362   @list = $self->directory_tree ()
363       Returns a list of directories used by this module.
364
365   @list = $self->packlist ()
366       Returns the "ExtUtils::Packlist" object for this module.
367
368   @list = $self->validate ()
369       Returns a list of files that are missing for this modules, but are
370       present in the .packlist file.
371
372   $bool = $self->add_to_includepath;
373       Adds the current modules path to @INC and $PERL5LIB. This allows you to
374       add the module from its build dir to your path.
375
376       It also adds the current modules "bin" and/or "script" paths to the
377       PATH.
378
379       You can reset $PATH, @INC and $PERL5LIB to their original state when
380       you started the program, by calling:
381
382           $self->parent->flush('lib');
383
384   $path = $self->best_path_to_module_build();
385       OBSOLETE
386
387       If a newer version of Module::Build is found in your path, it will
388       return this "special" path. If the newest version of "Module::Build" is
389       found in your regular @INC, the method will return false. This
390       indicates you do not need to add a special directory to your @INC.
391
392       Note that this is only relevant if you're building your own
393       "CPANPLUS::Dist::*" plugin -- the built-in dist types already have this
394       taken care of.
395

BUG REPORTS

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

AUTHOR

400       This module by Jos Boumans <kane@cpan.org>.
401
403       The CPAN++ interface (of which this module is a part of) is copyright
404       (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.
405
406       This library is free software; you may redistribute and/or modify it
407       under the same terms as Perl itself.
408
409
410
411perl v5.32.1                      2021-01-26               CPANPLUS::Module(3)
Impressum