1CPANPLUS::Module(3pm) Perl Programmers Reference Guide CPANPLUS::Module(3pm)
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
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 Returns a list of module objects the Bundle specifies.
281 This requires you to have extracted the bundle already, using the
283 "extract()" method.
284 Returns false on error.
286 $text = $self->readme
288 Fetches the readme belonging to this module and stores it under
289 "$obj->status->readme". Returns the readme as a string on success and
290 returns false on failure.
291 $version = $self->installed_version()
293 Returns the currently installed version of this module, if any.
294 $where = $self->installed_file()
296 Returns the location of the currently installed file of this module, if
297 any.
298 $dir = $self->installed_dir()
300 Returns the directory (or more accurately, the @INC handle) from which
301 this module was loaded, if any.
302 $bool = $self->is_uptodate([version => VERSION_NUMBER])
304 Returns a boolean indicating if this module is uptodate or not.
305 $href = $self->details()
307 Returns a hashref with key/value pairs offering more information about
308 a particular module. For example, for "Time::HiRes" it might look like
309 this:
310 Author Jarkko Hietaniemi (jhi@iki.fi)
312 Description High resolution time, sleep, and alarm
313 Development Stage Released
314 Installed File /usr/local/perl/lib/Time/Hires.pm
315 Interface Style plain Functions, no references used
316 Language Used C and perl, a C compiler will be needed
317 Package Time-HiRes-1.65.tar.gz
318 Public License Unknown
319 Support Level Developer
320 Version Installed 1.52
321 Version on CPAN 1.65
322 @list = $self->contains()
324 Returns a list of module objects that represent the modules also
325 present in the package of this module.
326 For example, for "Archive::Tar" this might return:
328 Archive::Tar
330 Archive::Tar::Constant
331 Archive::Tar::File
332 @list_of_hrefs = $self->fetch_report()
334 This function queries the CPAN testers database at
335 http://testers.cpan.org/ for test results of specified module objects,
336 module names or distributions.
337 Look at CPANPLUS::Internals::Report::_query_report() for details on the
339 options you can pass and the return value to expect.
340 $bool = $self->uninstall([type => [all|man|prog])
342 This function uninstalls the specified module object.
343 You can install 2 types of files, either "man" pages or "prog"ram
345 files. Alternately you can specify "all" to uninstall both (which is
346 the default).
347 Returns true on success and false on failure.
349 Do note that this does an uninstall via the so-called ".packlist", so
351 if you used a module installer like say, "ports" or "apt", you should
352 not use this, but use your package manager instead.
353 @modobj = $self->distributions()
355 Returns a list of module objects representing all releases for this
356 module on success, false on failure.
357 @list = $self->files ()
359 Returns a list of files used by this module, if it is installed.
360 @list = $self->directory_tree ()
362 Returns a list of directories used by this module.
363 @list = $self->packlist ()
365 Returns the "ExtUtils::Packlist" object for this module.
366 @list = $self->validate ()
368 Returns a list of files that are missing for this modules, but are
369 present in the .packlist file.
370 $bool = $self->add_to_includepath;
372 Adds the current modules path to @INC and $PERL5LIB. This allows you to
373 add the module from its build dir to your path.
374 You can reset @INC and $PERL5LIB to its original state when you started
376 the program, by calling:
377 $self->parent->flush('lib');
379 $path = $self->best_path_to_module_build();
381 OBSOLETE
382 If a newer version of Module::Build is found in your path, it will
384 return this "special" path. If the newest version of "Module::Build" is
385 found in your regular @INC, the method will return false. This
386 indicates you do not need to add a special directory to your @INC.
387 Note that this is only relevant if you're building your own
389 "CPANPLUS::Dist::*" plugin -- the built-in dist types already have this
390 taken care of.
391
393 Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>.
394
396 This module by Jos Boumans <kane@cpan.org>.
397
399 The CPAN++ interface (of which this module is a part of) is copyright
400 (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.
401 This library is free software; you may redistribute and/or modify it
403 under the same terms as Perl itself.
404perl v5.12.4 2011-06-07 CPANPLUS::Module(3pm)