NAME

Submodules - Efficient way to load or handle all submodules for a specific package.

SYNOPSIS

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.

EXPORT

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.

METHODS

find

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.

Importing a custom 'find' name that is not object oriented

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.

For example:

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

SEE ALSO

Submodules::Result 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

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/

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.

cpanm Submodules

perl -MCPAN -e shell
install Submodules