Submodules::Result - Efficient way to load or handle results from Submodules.
This is the object returned by Submodules->find. It has several methods that makes it easy to handle the tasks that are more commonly needed for a module. It's automagically stringified to the name of the module (in Module::Name format), but even inside string interpolation, you can access its properties as you would with a hashref:
package MyModule; use Submodules; for my $i (Submodules->find) { next if $i->Clobber; # Important $i->require; # Equivalent to 'require Some::Module' print "I found $i"; # Will print: I found Some::Module print "The path is $i->{RelPath}"; # Will print something like Some/Module.pm print "The absolute path is $i->{AbsPath}"; # Will print something like /usr/local/lib64/perl5/lib/Some/Module.pm print "The name of the module is $i->{Module}"; # Will print The name of the module is Some::Module }
All properties can be called as methods too. For example:
package MyModule; use Submodules; for my $i (Submodules->find) { # Used as method next if $i->Clobber; # Used as property (hash element) print "The value of Clobber is $i->{Clobber}"; }
This property correponds to the complete name of the module in the format of Some::Module.
This property refers to the last part of the name of the module. For example, Some::Module would be only Module.
This property contains a path exactly like the one that Perl stores internaly in its symbol table. This means that, for Some::Module, it will be Some/Module.pm, using forward slashes independently of the current operating system.
Corresponds to the absolute path where the module can be found. Depending on your system, the format can be different. For example, on Windows you'll get back-slashes on the path. This behavior comes directly from File::Spec.
Correspods to the relative path to the module. Similar to AbsPath except for being relative to the location of the current execution.
This property indicates that a module cannot (or should not) be visible by commands like use or require. It generally means that another module with the same name is the one being read and is masking this one. One example of this would be a core module that came with Perl by default, but was later upgraded and installed into the site/lib section. It's value is the absolute path to the first module that is directly masking it.
IMPORTANT: You should always test for this property and not load the code when true, unless you know what you are doing and you actually intended to use this module for that very purpose.
As mentioned in PROPERTIES, all properties can be called as methods too. Besides that, there are a few more useful methods:
This will read and return the contents of the module, as plain text. No code is parsed or executed.
This acts just like Perl's require, meaning that the module in question will be read, evaluated (executed) and the last statement will be returned, which in case of it not being a true value it will die. Nothing gets imported.
require
Use properly!
This acts just like Perl's use, meaning that it will do the same as in require, but it will also call ->import into the current namespace. However, you should understand that the native Perl's use is generally executed at compile time. For some modules and its features (like prototypes, constants, function names that can be used without parenthesis, and many other things), executing all that in compile time is crucial and can result in unexpected and hard to debug erros when executed at runtime.
use
->import
To avoid this, either use it only in modules that are supposed to be loaded at compile time (via use from another script calling it), or place your code inside a BEGIN block to force its execution at compile time.
BEGIN
This is an example:
use strict; use warnings; use Submodules; BEGIN { for my $i (Submodules->find('LWP::Protocol')) { next if $i->Clobber; $i->use; } }
This is the constructor and exists mainly for internal purposes. It requires all of its properties to be passed as arguments and that's something that Submodules does by itself. There should be no reason to use this method directly.
Read the documentation for Submodules to learn about its own methods.
Submodules for more detail on its own methods.
Francisco Zarabozo, <zarabozo at cpan.org>
<zarabozo at cpan.org>
Please report any bugs or feature requests to bug-submodules at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Submodules. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-submodules at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Submodules::Result
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Submodules
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Submodules
CPAN Ratings
http://cpanratings.perl.org/d/Submodules
Search CPAN
http://search.cpan.org/dist/Submodules/
Copyright 2015 Francisco Zarabozo.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Submodules, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Submodules
CPAN shell
perl -MCPAN -e shell install Submodules
For more information on module installation, please visit the detailed CPAN module installation guide.