/ 
Submodules-1.0015
River stage one • 1 direct dependent • 2 total dependents
/ Submodules::Result

NAME

Submodules::Result - Efficient way to load or handle results from Submodules.

SYNOPSIS

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
}

PROPERTIES

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}";
}

Module

This property correponds to the complete name of the module in the format of Some::Module.

Name

This property refers to the last part of the name of the module. For example, Some::Module would be only Module.

Path

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.

AbsPath

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.

RelPath

Correspods to the relative path to the module. Similar to AbsPath except for being relative to the location of the current execution.

Clobber

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.

METHODS

As mentioned in PROPERTIES, all properties can be called as methods too. Besides that, there are a few more useful methods:

read

This will read and return the contents of the module, as plain text. No code is parsed or executed.

require

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.

use

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.

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.

This is an example:

use strict;
use warnings;
use Submodules;

BEGIN {
    for my $i (Submodules->find('LWP::Protocol')) {
        next if $i->Clobber;
        $i->use;
    }
}

new

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.

SEE ALSO

Submodules for more detail on its own methods.

AUTHOR

Francisco Zarabozo, <zarabozo at cpan.org>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Submodules::Result

You can also look for information at:

LICENSE AND COPYRIGHT

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.