1CPANPLUS::Module(3) User Contributed Perl Documentation CPANPLUS::Module(3)
2
6 CPANPLUS::Module - CPAN module objects for CPANPLUS
7
9 ### get a module object from the CPANPLUS::Backend object
10 my $mod = $cb->module_tree('Some::Module');
11 ### accessors
13 $mod->version;
14 $mod->package;
15 ### methods
17 $mod->fetch;
18 $mod->extract;
19 $mod->install;
20
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 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
31 accessors ()
32 Returns a list of all accessor methods to the object
33
35 An objects of this class has the following accessors:
36 name
38 Name of the module.
39 module
41 Name of the module.
42 version
44 Version of the module. Defaults to '0.0' if none was provided.
45 path
47 Extended path on the mirror.
48 comment
50 Any comment about the module -- largely unused.
51 package
53 The name of the package.
54 description
56 Description of the module -- only registered modules have this.
57 dslip
59 The five character dslip string, that represents meta-data of the
60 module -- again, only registered modules have this.
61 status
63 The "CPANPLUS::Module::Status" object associated with this object.
64 (see below).
65 author
67 The "CPANPLUS::Module::Author" object associated with this object.
68 parent
70 The "CPANPLUS::Internals" object that spawned this module object.
71
73 "CPANPLUS" caches a lot of results from method calls and saves data it
74 collected along the road for later reuse.
75 "CPANPLUS" uses this internally, but it is also available for the end
77 user. You can get a status object by calling:
78 $modobj->status
80 You can then query the object as follows:
82 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 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 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 Undefined if you didn't specify a separate format to install
100 through.
101 prereqs | requires
103 A hashref of prereqs this distribution was found to have. Will look
104 something like this:
105 { Carp => 0.01, strict => 0 }
107 Might be undefined if the distribution didn't have any
109 prerequisites.
110 configure_requires
112 Like prereqs, but these are necessary to be installed before the
113 build process can even begin.
114 signature
116 Flag indicating, if a signature check was done, whether it was OK
117 or not.
118 extract
120 The directory this distribution was extracted to.
121 fetch
123 The location this distribution was fetched to.
124 readme
126 The text of this distributions README file.
127 uninstall
129 Flag indicating if an uninstall call was done successfully.
130 created
132 Flag indicating if the "create" call to your dist object was done
133 successfully.
134 installed
136 Flag indicating if the "install" call to your dist object was done
137 successfully.
138 checksums
140 The location of this distributions CHECKSUMS file.
141 checksum_ok
143 Flag indicating if the checksums check was done successfully.
144 checksum_value
146 The checksum value this distribution is expected to have
147
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 This example illustrates a "new()" call with all required arguments:
155 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 Every accessor is also a valid option to pass to "new".
165 Returns a module object on success and false on failure.
167 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 Returns the installer type on success, and false on error.
232 $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 The optional "args" hashref is passed on to the specific distribution
239 types' "create" method after being dereferenced.
240 Returns a distribution object on success, false on failure.
242 See "CPANPLUS::Dist" for details.
244 $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 Returns true on success, false on failure.
251 $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 Returns true on success, false on failure.
257 $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 Returns true on success, false on failure.
264 $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 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 See "CPANPLUS::Internals::Fetch", "CPANPLUS::Internals::Extract" and
276 "CPANPLUS::Dist" for details.
277 Returns true on success, false on failure.
279 @list = $self->bundle_modules()
281 Returns a list of module objects the Bundle specifies.
282 This requires you to have extracted the bundle already, using the
284 "extract()" method.
285 Returns false on error.
287 $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 $version = $self->installed_version()
294 Returns the currently installed version of this module, if any.
295 $where = $self->installed_file()
297 Returns the location of the currently installed file of this module, if
298 any.
299 $dir = $self->installed_dir()
301 Returns the directory (or more accurately, the @INC handle) from which
302 this module was loaded, if any.
303 $bool = $self->is_uptodate([version => VERSION_NUMBER])
305 Returns a boolean indicating if this module is uptodate or not.
306 $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 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 @list = $self->contains()
325 Returns a list of module objects that represent the modules also
326 present in the package of this module.
327 For example, for "Archive::Tar" this might return:
329 Archive::Tar
331 Archive::Tar::Constant
332 Archive::Tar::File
333 @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 Look at CPANPLUS::Internals::Report::_query_report() for details on the
340 options you can pass and the return value to expect.
341 $bool = $self->uninstall([type => [all|man|prog])
343 This function uninstalls the specified module object.
344 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 Returns true on success and false on failure.
350 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 @modobj = $self->distributions()
356 Returns a list of module objects representing all releases for this
357 module on success, false on failure.
358 @list = $self->files ()
360 Returns a list of files used by this module, if it is installed.
361 @list = $self->directory_tree ()
363 Returns a list of directories used by this module.
364 @list = $self->packlist ()
366 Returns the "ExtUtils::Packlist" object for this module.
367 @list = $self->validate ()
369 Returns a list of files that are missing for this modules, but are
370 present in the .packlist file.
371 $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 It also adds the current modules "bin" and/or "script" paths to the
377 PATH.
378 You can reset $PATH, @INC and $PERL5LIB to their original state when
380 you started the program, by calling:
381 $self->parent->flush('lib');
383 $path = $self->best_path_to_module_build();
385 OBSOLETE
386 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 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
397 Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>.
398
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 This library is free software; you may redistribute and/or modify it
407 under the same terms as Perl itself.
408perl v5.32.1 2021-01-26 CPANPLUS::Module(3)