---
name: "relative"
section: "3pm"
platform: "linux"
package: "librelative-perl"
version: "0.04-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/relative"
---

# relative(3pm)

Load modules with relative names

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