relative(3pm)

✨ relative — the manual page, but make it cute ✨

okay bestie, gather round, because this is the Perl module that lets you stop typing your entire namespace over and over like some kind of namespace peasant. it's called relative, it lives at relative(3pm) in the Perl docs, and honestly? it's giving main character energy for people who are tired of writing BigApp::Report::Create when they could just write Create. 💅

---

🌸 NAME 🌸

relative — load modules using only parts of their name. no cap, that's the whole bit.

---

🎀 VERSION 🎀

Version 0.04. that's the one. periodt.

---

🦋 SYNOPSIS 🦋

here's the vibe in code form, and every line is exact so don't @ me:

    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

see how Create just knew you meant BigApp::Report::Create? that's the whole point. and ..::Utils reached upward in the hierarchy like a girl climbing the family tree. 🧚

---

💖 DESCRIPTION 💖

so, the tea: this module lets you load modules using only parts of their name, relative to the module you're currently in, or relative to some other module you point at.

by default, module names get searched below the current module. but you can search upper in the hierarchy too, using the ..:: syntax. it's giving "look up, not down". 👑

and to further loosen the namespace coupling (yes, we love a loose coupling era), import hands you back the full names of the loaded modules, which makes object-oriented code so much 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;

you can also write all of that with aliases, if you're feeling extra:

    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;

Factory->new. that's it. that's the post. 🔥

---

🌈 IMPORT OPTIONS 🌈

import options can be handed over as a 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 ...);

and because the author wanted your life to be easier, options can also be given as dash-prefixed params:

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

here are the options that are actually available, bestie:

• to — tells relative to search for modules inside a different hierarchy. point it somewhere else and it goes there.

examples, so you can see it in the wild:

    # 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 — creates constants, each named with the last component of a loaded module, and each returning that module's full name. and yes, this is very similar to what aliased does — it got added because Ovid requested it. so shoutout to Ovid, the request was granted. :-)

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;

heads up bestie: import will die the second a module can't be loaded. no quiet failure, no "oops where'd my module go". it just dies. dramatic, honestly, but fair. 💀

and for the return values: import returns the full names of the loaded modules when you call it in list context, or just the last one when you call it in scalar context. iykyk.

---

👑 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>. here's the deal: he'll get notified, and then you'll automatically get notified about progress on your bug as the changes happen. that's a mutual notification situation and we love that for everyone. 🫶

---

⭐ SUPPORT ⭐

you can find documentation for this module with the perldoc command. yes, that perldoc command:

    perldoc relative

you can also look for information at these places:

• 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 🍓

thank you to Aristotle Pagaltzis, Andy Armstrong, Ken Williams and Curtis Poe for their suggestions and ideas. icons, all of them. 💜

---

💅 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.

---

and that's the whole page, bestie. this was relative for Perl, and the whole thing was served up by perl v5.36.0 back on 2022-11-19 — so go forth, use relative module names, and remember: your namespace doesn't have to be your whole personality. bye, ily 🎀💖✨