Submodules - Efficient way to load or handle all submodules for a specific package.
This module will walk the paths that Perl itself walks whenever a module is used or required and will return all the submodules found for a specific package (or the current package if none is specified).
This is useful for many different cases. For example, when you work on a module that is always going to use or require all of its submodules. Suppose the module MyModule has many submodules that is going to use from the beggining (e.g. MyModule::Protocol, MyModule::Result, MyModule::Config, MyModule::Plugins, and so on). You would then normally write something like:
package MyModule; use MyModule::Protocol; use MyModule::Result; use MyModule::Config; use MyModule::Plugins; use MyModule::Plugins::PlugA; use MyModule::Plugins::PlugB; use MyModule::Plugins::PlugC; use MyModule::SomethingElse; # ...and so on with all of your submodules
Now, imagine you constantly add submodules and you need to keep this list updated too. Instead, you can use this module in a very efficient way:
package MyModule; use Submodules; for my $i (Submodules->find) { $i->require; } # Maybe you need to do the same for # a package different than the current: for my $i (Submodules->find('LWP')) { # All LWP & LWP submodules $i->require; } # Or maybe you only want a subset: for my $i (Submodules->find('LWP::Protocol')) { # All LWP protocols $i->require; }
Not only that will save you lots of lines, but it will always include new submodules without you having to go back to this one to include them.
Each of the elements returned by the find method is an instance of Submodules::Result, which is automagically stringified to the name of the module (as in Some::Module) but has useful methods that can do a lot more.
Nothing is exported by default. However, you can import a non OO version of find with the name that you prefere. For example, let's say you'd like that function to be called walk. You'd then call this module like this:
use strict; use Submodules 'walk'; # The new 'walk' function doesn't # need you to quote the module name: for my $i (walk LWP::Protocol) { print "Found module $i\n"; }
You can use any name you want and it'll work as long as it is not already defined in that namespace.
This is basically the only method you'll work with. It can take an optional argument with the name of a package. If that argument is not supplied, then the current package will be used. It will return instances of Submodules::Result.
For example:
# This will find all submodules from the current package for my $i (Submodules->find) { $i->require; say "Required $i"; } # This will find all submodules from package LWP::Protocol for my $i (Submodules->find('LWP::Protocol')) { $i->require; say "Required $i"; }
Read the documentation for Submodules::Result to learn about its own methods.
You can import a non object oriented version of find that also accepts module names without quoting them (barewords). This might be more for the taste of some and considered ugly by others. It all depends on you, nothing gets imported by default.
You can chose any valid function name for it and it will be created as long as it is not already defined in that namespace. It will, just like find, return instances of Submodules::Result.
Submodules::Result 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
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.