/ 
package-compute-0.005
River stage zero No dependents
/ package::compute

NAME

package::compute - stop hard-coding your package names

SYNOPSIS

package Foo::Bar;  # this is a hard-coded package name
use 5.010;

{
   use package::compute "../Quux";
   say __PACKAGE__;              # says "Foo::Quux";
   say __RPACKAGE__("./Xyzzy");  # says "Foo::Quux::Xyzzy";
   
   sub hello { say __PACKAGE__ };
}

say __PACKAGE__;   # says "Foo::Bar" (lexically scoped!)
Foo::Quux->hello;  # says "Foo::Quux"

DESCRIPTION

This module allows you to compute package names on the fly at compile time, rather than hard-coding them as barewords. It is the solution to the problem (if indeed you consider it to be a problem at all) that you cannot write this in Perl:

package $blah;

This module uses B::Hooks::Parser to accomplish its evil goals.

Using this module at all is probably a very bad idea.

Package Specification

The general syntax for specifying a package with this module is:

use package::compute EXPR;

Where EXPR is an arbitrary expression which will (caveat!) be evaluated at compile time, and interpreted roughly the way Perl interprets package names, with the following bonus features:

  • If the package name expression is a coderef, then that coderef is called and the return value is used instead.

  • Slashes may be used to separate package name components in addition to the usual Perl "::" and deprecated "'" package separators.

  • The component "." at the start of the package name refers to the caller. ("." elsewhere is a no-op.)

  • The component ".." climbs "up" the package hierarchy.

  • The component "..." climbs "up" the package hierarchy by two levels. Et cetera.

Thus the following are all valid ways of expressing package "Foo::Bar":

### 
use package::compute "Foo::Bar";
####

### Using a coderef
use package::compute sub { join q(::) qw( Foo Bar ) };
####

#### Relative package name
package Foo;
use package::compute "./Bar";
####

### Climbing the package hierarchy
package Foo::XXX;
use package::compute "../Bar";
####

### Climbing the package hierarchy twice
package Foo::XXX::YYY;
use package::compute "../../Bar";
####

### Climbing the package hierarchy twice - shortcut
package Foo::XXX::YYY;
use package::compute ".../Bar";
####

As a special case, you can also do:

use package::compute -filename;

Which will attempt to determine the package name based on the filename it is defined in, much like autopackage does.

Also:

use package::compute -anon;

Will compute an "anonymous" (i.e. arbitrary) package name.

Utility Function

This module also exports a utility function:

__RPACKAGE__($name)

Returns a package name as a string, computed in the same way as use package::compute does. An example of its use for object-oriented code:

package MyProject;

{
	use package::compute './Person';
	use Moose;
	has name => (is => 'ro');
}

my $bob = __RPACKAGE__('./Person')->new(name => "Robert");

As you can see, this makes it possible to avoid hard-coded references to the MyProject::Person class.

__RPACKAGE__ doesn't support the special -filename and -anon options.

It is possible to import the __RPACKAGE__ function alone, without the package declaration magic using:

use package::compute undef;

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=package-compute.

SEE ALSO

autopackage, Package::Relative.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.