relative (3pm)

Version 0.04

    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

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 \*(C`..::\*(C' syntax.

In order to further loosen the namespace coupling, \*(C`import\*(C' 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 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:

• \*(C`to\*(C' 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);

• \*(C`aliased\*(C' 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 \*(C`aliased\*(C' does as it was added per Ovid request \*(C`:-)\*(C' 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;

\*(C`import\*(C' will \*(C`die\*(C' as soon as a module can't be loaded.

\*(C`import\*(C' returns the full names of the loaded modules when called in list context, or the last one when called in scalar context.

Se\*'bastien Aperghis-Tramoni, \*(C`<sebastien at aperghis.net>\*(C'

Please report any bugs or feature requests to \*(C`bug-relative at rt.cpan.org\*(C', 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.

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

perldoc relative

You can also look for information at:

• AnnoCPAN: Annotated \s-1CPAN\s0 documentation <http://annocpan.org/dist/relative>

• \s-1CPAN\s0 Ratings <http://cpanratings.perl.org/d/relative>

• \s-1RT:\s0 \s-1CPAN\s0's request tracker <http://rt.cpan.org/NoAuth/Bugs.html?Dist=relative>

• Search \s-1CPAN\s0 <http://search.cpan.org/dist/relative>

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

Copyright 2007 Se\*'bastien 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.