NAME

       relative - Load modules with relative names

VERSION

       Version 0.04

SYNOPSIS

           package BigApp::Report;

           use relative qw(Create Publish);
           # loads BigApp::Report::Create, BigApp::Report::Publish

           use relative qw(..::Utils);
           # loads BigApp::Utils

           use relative -to => "Enterprise::Framework" => qw(Base Factory);
           # loads Enterprise::Framework::Base, Enterprise::Framework::Factory

DESCRIPTION

       This module allows you to load modules using only parts of their name, relatively to the
       current module or to a given module. Module names are by default searched below the
       current module, but can be searched upper in the hierarchy using the "..::" syntax.

       In order to further loosen the namespace coupling, "import" returns the full names of the
       loaded modules, making object-oriented code easier to write:

           use relative;

           my ($Maker, $Publisher) = import relative qw(Create Publish);
           my $report    = $Maker->new;
           my $publisher = $Publisher->new;

           my ($Base, $Factory) = import relative -to => "Enterprise::Framework"
                                       => qw(Base Factory);
           my $thing = $Factory->new;

       This can also be written using aliases:

           use relative -aliased => qw(Create Publish);
           my $report    = Create->new;
           my $publisher = Publisher->new;

           use relative -to => "Enterprise::Framework", -aliased => qw(Base Factory);
           my $thing = Factory->new;

IMPORT OPTIONS

       Import options can be given as an hashref or an arrayref as the first argument:

           # options as a hashref
           import relative { param => value, ... },  qw(Name ...);

           # options as an arrayref
           import relative [ param => value, ... ],  qw(Name ...);

       In order to simplyfing syntax, options can also be given as dash-prefixed params:

           import relative -param => value, qw(name ...);

       Available options:

       •   "to" can be used to indicate another hierarchy to search modules inside.

           Examples

               # in a hashref:
               import relative { to => "Some::Other::Namespace" }, qw(Other Modules);

               # as dash-param:
               import relative -to => "Some::Other::Namespace", qw(Other Modules);

       •   "aliased" will create constants, named with the last component of each loaded module,
           returning its corresponding full name. Yes, this feature is very similar to what
           "aliased" does as it was added per Ovid request ":-)"

           Examples

               # in a hashref:
               import relative { aliased => 1 }, qw(Whack Zlonk);
               my $frob = Whack->fizzle;

               # as dash-param:
               import relative -aliased, qw(Whack Zlonk);
               my $frob = Whack->fizzle;

       "import" will "die" as soon as a module can't be loaded.

       "import" returns the full names of the loaded modules when called in list context, or the
       last one when called in scalar context.

AUTHOR

       Sebastien Aperghis-Tramoni, "<sebastien at aperghis.net>"

BUGS

       Please report any bugs or feature requests to "bug-relative at rt.cpan.org", or through
       the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=relative>.  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 relative

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/relative>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/relative>

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=relative>

       •   Search CPAN

           <http://search.cpan.org/dist/relative>

ACKNOWLEDGEMENTS

       Thanks to Aristotle Pagaltzis, Andy Armstrong, Ken Williams and Curtis Poe for their
       suggestions and ideas.

COPYRIGHT & LICENSE

       Copyright 2007 Sebastien Aperghis-Tramoni, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.