1CPANPLUS::Module(3) User Contributed Perl Documentation CPANPLUS::Module(3)
2
6 CPANPLUS::Module
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
34
36 An objects of this class has the following accessors:
37 name
39 Name of the module.
40 module
42 Name of the module.
43 version
45 Version of the module. Defaults to '0.0' if none was provided.
46 path
48 Extended path on the mirror.
49 comment
51 Any comment about the module -- largely unused.
52 package
54 The name of the package.
55 description
57 Description of the module -- only registered modules have this.
58 dslip
60 The five character dslip string, that represents meta-data of the
61 module -- again, only registered modules have this.
62 status
64 The "CPANPLUS::Module::Status" object associated with this object.
65 (see below).
66 author
68 The "CPANPLUS::Module::Author" object associated with this object.
69 parent
71 The "CPANPLUS::Internals" object that spawned this module object.
72
74 "CPANPLUS" caches a lot of results from method calls and saves data it
75 collected along the road for later reuse.
76 "CPANPLUS" uses this internally, but it is also available for the end
78 user. You can get a status object by calling:
79 $modobj->status
81 You can then query the object as follows:
83 installer_type
85 The installer type used for this distribution. Will be one of
86 'makemaker' or 'build'. This determines whether "CPAN‐
87 PLUS::Dist::MM" or "CPANPLUS::Dist::Build" will be used to build
88 this distribution.
89 dist_cpan
91 The dist object used to do the CPAN-side of the installation.
92 Either a "CPANPLUS::Dist::MM" or "CPANPLUS::Dist::Build" object.
93 dist
95 The custom dist object used to do the operating specific side of
96 the installation, if you've chosen to use this. For example, if
97 you've chosen to install using the "ports" format, this may be a
98 "CPANPLUS::Dist::Ports" object.
99 Undefined if you didn't specify a separate format to install
101 through.
102 prereqs
104 A hashref of prereqs this distribution was found to have. Will look
105 something like this:
106 { Carp => 0.01, strict => 0 }
108 Might be undefined if the distribution didn't have any prerequi‐
110 sites.
111 signature
113 Flag indicating, if a signature check was done, whether it was OK
114 or not.
115 extract
117 The directory this distribution was extracted to.
118 fetch
120 The location this distribution was fetched to.
121 readme
123 The text of this distributions README file.
124 uninstall
126 Flag indicating if an uninstall call was done successfully.
127 created
129 Flag indicating if the "create" call to your dist object was done
130 successfully.
131 installed
133 Flag indicating if the "install" call to your dist object was done
134 successfully.
135 checksums
137 The location of this distributions CHECKSUMS file.
138 checksum_ok
140 Flag indicating if the checksums check was done successfully.
141 checksum_value
143 The checksum value this distribution is expected to have
144
146 $self = CPANPLUS::Module::new( OPTIONS )
147 This method returns a "CPANPLUS::Module" object. Normal users should
149 never call this method directly, but instead use the "CPANPLUS::Back‐
150 end" to obtain module objects.
151 This example illustrates a "new()" call with all required arguments:
153 CPANPLUS::Module->new(
155 module => 'Foo',
156 path => 'authors/id/A/AA/AAA',
157 package => 'Foo-1.0.tgz',
158 author => $author_object,
159 _id => INTERNALS_OBJECT_ID,
160 );
161 Every accessor is also a valid option to pass to "new".
163 Returns a module object on success and false on failure.
165 $mod->package_name
167 Returns the name of the package a module is in. For "Acme::Bleach" that
169 might be "Acme-Bleach".
170 $mod->package_version
172 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
177 Returns the suffix added by the compression method of a package a cer‐
179 tain module is in. For a module in "Acme-Bleach-1.1.tar.gz", this would
180 be "tar.gz".
181 $mod->package_is_perl_core
183 Returns a boolean indicating of the package a particular module is in,
185 is actually a core perl distribution.
186 $mod->module_is_supplied_with_perl_core( [version => $]] )
188 Returns a boolean indicating whether "ANY VERSION" of this module was
190 supplied with the current running perl's core package.
191 $mod->is_bundle
193 Returns a boolean indicating if the module you are looking at, is actu‐
195 ally a bundle. Bundles are identified as modules whose name starts with
196 "Bundle::".
197 $mod->is_third_party
199 Returns a boolean indicating whether the package is a known third-party
201 module (i.e. it's not provided by the standard Perl distribution and is
202 not available on the CPAN, but on a third party software provider).
203 See Module::ThirdParty for more details.
204 $mod->third_party_information
206 Returns a reference to a hash with more information about a third-party
208 module. See the documentation about "module_information()" in Mod‐
209 ule::ThirdParty for more details.
210 $clone = $self->clone
212 Clones the current module object for tinkering with. It will have a
214 clean "CPANPLUS::Module::Status" object, as well as a fake "CPAN‐
215 PLUS::Module::Author" object.
216 $where = $self->fetch
218 Fetches the module from a CPAN mirror. Look at CPANPLUS::Inter‐
220 nals::Fetch::_fetch() for details on the options you can pass.
221 $path = $self->extract
223 Extracts the fetched module. Look at CPANPLUS::Inter‐
225 nals::Extract::_extract() for details on the options you can pass.
226 $type = $self->get_installer_type([prefer_makefile => BOOL])
228 Gets the installer type for this module. This may either be "build" or
230 "makemaker". If "Module::Build" is unavailable or no installer type is
231 available, it will fall back to "makemaker". If both are available, it
232 will pick the one indicated by your config, or by the "prefer_makefile"
233 option you can pass to this function.
234 Returns the installer type on success, and false on error.
236 $dist = $self->dist([target => 'prepare⎪create', format => DISTRIBU‐
238 TION_TYPE, args => {key => val}]);
239 Create a distribution object, ready to be installed. Distribution type
241 defaults to your config settings
242 The optional "args" hashref is passed on to the specific distribution
244 types' "create" method after being dereferenced.
245 Returns a distribution object on success, false on failure.
247 See "CPANPLUS::Dist" for details.
249 $bool = $mod->prepare( )
251 Convenience method around "install()" that prepares a module without
253 actually building it. This is equivalent to invoking "install" with
254 "target" set to "prepare"
255 Returns true on success, false on failure.
257 $bool = $mod->create( )
259 Convenience method around "install()" that creates a module. This is
261 equivalent to invoking "install" with "target" set to "create"
262 Returns true on success, false on failure.
264 $bool = $mod->test( )
266 Convenience wrapper around "install()" that tests a module, without
268 installing it. It's the equivalent to invoking "install()" with "tar‐
269 get" set to "create" and "skiptest" set to 0.
270 Returns true on success, false on failure.
272 $bool = $self->install([ target => 'prepare⎪create⎪install', format =>
274 FORMAT_TYPE, extractdir => DIRECTORY, fetchdir => DIRECTORY, prefer_bin
275 => BOOL, force => BOOL, verbose => BOOL, ..... ]);
276 Installs the current module. This includes fetching it and extracting
278 it, if this hasn't been done yet, as well as creating a distribution
279 object for it.
280 This means you can pass it more arguments than described above, which
282 will be passed on to the relevant methods as they are called.
283 See "CPANPLUS::Internals::Fetch", "CPANPLUS::Internals::Extract" and
285 "CPANPLUS::Dist" for details.
286 Returns true on success, false on failure.
288 Returns a list of module objects the Bundle specifies.
290 This requires you to have extracted the bundle already, using the
292 "extract()" method.
293 Returns false on error.
295 $text = $self->readme
297 Fetches the readme belonging to this module and stores it under
299 "$obj->status->readme". Returns the readme as a string on success and
300 returns false on failure.
301 $version = $self->installed_version()
303 Returns the currently installed version of this module, if any.
305 $where = $self->installed_file()
307 Returns the location of the currently installed file of this module, if
309 any.
310 $bool = $self->is_uptodate([version => VERSION_NUMBER])
312 Returns a boolean indicating if this module is uptodate or not.
314 $href = $self->details()
316 Returns a hashref with key/value pairs offering more information about
318 a particular module. For example, for "Time::HiRes" it might look like
319 this:
320 Author Jarkko Hietaniemi (jhi@iki.fi)
322 Description High resolution time, sleep, and alarm
323 Development Stage Released
324 Installed File /usr/local/perl/lib/Time/Hires.pm
325 Interface Style plain Functions, no references used
326 Language Used C and perl, a C compiler will be needed
327 Package Time-HiRes-1.65.tar.gz
328 Public License Unknown
329 Support Level Developer
330 Version Installed 1.52
331 Version on CPAN 1.65
332 @list = $self->contains()
334 Returns a list of module objects that represent the modules also
336 present in the package of this module.
337 For example, for "Archive::Tar" this might return:
339 Archive::Tar
341 Archive::Tar::Constant
342 Archive::Tar::File
343 @list_of_hrefs = $self->fetch_report()
345 This function queries the CPAN testers database at
347 http://testers.cpan.org/ for test results of specified module objects,
348 module names or distributions.
349 Look at CPANPLUS::Internals::Report::_query_report() for details on the
351 options you can pass and the return value to expect.
352 $bool = $self->uninstall([type => [all⎪man⎪prog])
354 This function uninstalls the specified module object.
356 You can install 2 types of files, either "man" pages or "prog"ram
358 files. Alternately you can specify "all" to uninstall both (which is
359 the default).
360 Returns true on success and false on failure.
362 Do note that this does an uninstall via the so-called ".packlist", so
364 if you used a module installer like say, "ports" or "apt", you should
365 not use this, but use your package manager instead.
366 @modobj = $self->distributions()
368 Returns a list of module objects representing all releases for this
370 module on success, false on failure.
371 @list = $self->files ()
373 Returns a list of files used by this module, if it is installed.
375 @list = $self->directory_tree ()
377 Returns a list of directories used by this module.
379 @list = $self->packlist ()
381 Returns the "ExtUtils::Packlist" object for this module.
383 @list = $self->validate ()
385 Returns a list of files that are missing for this modules, but are
387 present in the .packlist file.
388 $bool = $self->add_to_includepath;
390 Adds the current modules path to @INC and $PERL5LIB. This allows you to
392 add the module from it's build dir to your path.
393 You can reset @INC and $PERL5LIB to it's original state when you
395 started the program, by calling:
396 $self->parent->flush('lib');
398 $path = $self->best_path_to_module_build();
400 OBSOLETE
402 If a newer version of Module::Build is found in your path, it will
404 return this "special" path. If the newest version of "Module::Build" is
405 found in your regular @INC, the method will return false. This indi‐
406 cates you do not need to add a special directory to your @INC.
407 Note that this is only relevant if you're building your own "CPAN‐
409 PLUS::Dist::*" plugin -- the built-in dist types already have this
410 taken care of.
411
413 Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>.
414
416 This module by Jos Boumans <kane@cpan.org>.
417
419 The CPAN++ interface (of which this module is a part of) is copyright
420 (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.
421 This library is free software; you may redistribute and/or modify it
423 under the same terms as Perl itself.
424perl v5.8.8 2007-03-31 CPANPLUS::Module(3)