Package::Variant - Parameterizable packages
Creation of anonymous variants:
# declaring a variable Moo role
package My::VariableRole::ObjectAttr;
use strictures 2;
use Package::Variant
# what modules to 'use'
importing => ['Moo::Role'],
# proxied subroutines
subs => [ qw(has around before after with) ];
sub make_variant {
my ($class, $target_package, %arguments) = @_;
# access arguments
my $name = $arguments{name};
# use proxied 'has' to add an attribute
has $name => (is => 'lazy');
# install a builder method
install "_build_${name}" => sub {
return $arguments{class}->new;
};
}
# using the role
package My::Class::WithObjectAttr;
use strictures 2;
use Moo;
use My::VariableRole::ObjectAttr;
with ObjectAttr(name => 'some_obj', class => 'Some::Class');
# using our class
my $obj = My::Class::WithObjectAttr->new;
$obj->some_obj; # returns a Some::Class instance
And the same thing, only with named variants:
# declaring a variable Moo role that can be named
package My::VariableRole::ObjectAttrNamed;
use strictures 2;
use Package::Variant importing => ['Moo::Role'],
subs => [ qw(has around before after with) ];
use Module::Runtime 'module_notional_filename'; # only if you need protection
# this method is run at variant creation time to determine its custom
# package name. it can use the arguments or do something entirely else.
sub make_variant_package_name {
my ($class, $package, %arguments) = @_;
$package = "Private::$package"; # you can munge the input here if you like
# only if you *need* protection
die "Won't clobber $package" if $INC{module_notional_filename $package};
return $package;
}
# same as in the example above, except for the argument list. in this example
# $package is the user input, and
# $target_package is the actual package in which the variant gets installed
sub make_variant {
my ($class, $target_package, $package, %arguments) = @_;
my $name = $arguments{name};
has $name => (is => 'lazy');
install "_build_${name}" => sub {return $arguments{class}->new};
}
# using the role
package My::Class::WithObjectAttr;
use strictures 2;
use Moo;
use My::VariableRole::ObjectAttrNamed;
# create the role under a specific name
ObjectAttrNamed "My::Role" => (name => 'some_obj', class => 'Some::Class');
# and use it
with "Private::My::Role";
# using our class
my $obj = My::Class::WithObjectAttr->new;
$obj->some_obj; # returns a Some::Class instance
This module allows you to build a variable package that contains a package
template and can use it to build variant packages at runtime.
Your variable package will export a subroutine which will build a variant
package, combining its arguments with the template, and return the name of the
new variant package.
The implementation does not care about what kind of packages it builds, be they
simple function exporters, classes, singletons or something entirely different.
There are two important parts to creating a variable package. You first
have to give Package::Variant some basic information about what kind of
variant packages you want to provide, and how. The second part is implementing a
method which builds the components of the variant packages that use the user's
arguments or cannot be provided with a static import.
When you use Package::Variant , you pass along some arguments that
describe how you intend to build your variants.
use Package::Variant
importing => { $package => \@import_arguments, ... },
subs => [ @proxied_subroutine_names ];
The importing option needs to be a hash or array reference with
package names to be use d as keys, and array references containing the
import arguments as values. These packages will be imported into every new
variant package, to provide static functionality of the variant packages and to
set up every declarative subroutine you require to build variants package
components. The next option will allow you to use these functions. See
importing for more options. You can omit empty import argument lists when
passing an array reference.
The subs option is an array reference of subroutine names that are
exported by the packages specified with importing. These subroutines
will be proxied from your variable package to the variant to be
generated.
With importing initializing your package and subs declaring what
subroutines you want to use to build a variant, you can now write a
make_variant method building your variants.
Every time a user requests a new variant, a method named make_variant
will be called with the name of the target package and the arguments from
the user.
It can then use the proxied subroutines declared with subs to
customize the variant package. An install subroutine is exported as well
allowing you to dynamically install methods into the variant package. If these
options aren't flexible enough, you can use the passed name of the variant
package to do any other kind of customizations.
sub make_variant {
my ($class, $target, @arguments) = @_;
# ...
# customization goes here
# ...
}
When the method is finished, the user will receive the name of the new variant
package you just set up.
After your variable package is created
your users can get a variant generator subroutine by simply importing
your package.
use My::Variant;
my $new_variant_package = Variant(@variant_arguments);
# the variant package is now fully initialized and used
You can import the subroutine under a different name by specifying an as
argument.
For regular uses, the normal import provides
more than enough flexibility. However, if you want to create variants of
dynamically determined packages, you can use the build_variant_of
method.
You can use this to create variants of other packages and pass arguments
on to them to allow more modular and extensible variants.
These are the options that can be passed when importing
Package::Variant . They describe the environment in which the variants
are created.
use Package::Variant
importing => { $package => \@import_arguments, ... },
subs => [ @proxied_subroutines ];
This option is a hash reference mapping package names to array references
containing import arguments. The packages will be imported with the given
arguments by every variant before the make_variant method is asked
to create the package (this is done using the Import::Into manpage).
If import order is important to you, you can also pass the importing
arguments as a flat array reference:
use Package::Variant
importing => [ 'PackageA', 'PackageB' ];
# same as
use Package::Variant
importing => [ 'PackageA' => [], 'PackageB' => [] ];
# or
use Package::Variant
importing => { 'PackageA' => [], 'PackageB' => [] };
The import method will be called even if the list of import arguments is
empty or not specified,
If you just want to import a single package's default exports, you can
also pass a string instead:
use Package::Variant importing => 'Package';
An array reference of strings listing the names of subroutines that should
be proxied. These subroutines are expected to be installed into the new
variant package by the modules imported with importing. Subroutines
with the same name will be available in your variable package, and will
proxy through to the newly created package when used within
make_variant.
These are methods on the variable package you declare when you import
Package::Variant .
Some::Variant::Package->make_variant( $target, @arguments );
You need to provide this method. This method will be called for every
new variant of your package. This method should use the subroutines
declared in subs to customize the new variant package.
This is a class method receiving the $target package and the
@arguments defining the requested variant.
Some::Variant::Package->make_variant_package_name( @arguments );
You may optionally provide this method. If present, this method will be
used to determine the package name for a particular variant being constructed.
If you do not implement it, a unique package name something like
Some::Variant::Package::_Variant_A003
will be created for you.
use Some::Variant::Package;
my $variant_package = Package( @arguments );
This method is provided for you. It will allow a user to use your
package and receive a subroutine taking @arguments defining the variant
and returning the name of the newly created variant package.
The following options can be specified when importing:
use Some::Variant::Package ();
my $variant_package = Some::Variant::Package->build_variant( @arguments );
This method is provided for you. It will generate a variant package
and return its name, just like the generator sub provided by
import. This allows you to avoid importing anything into the
consuming package.
These methods are available on Package::Variant itself.
my $variant_package = Package::Variant
->build_variant_of($variable_package, @arguments);
This is the dynamic method of creating new variants. It takes the
$variable_package , which is a pre-declared variable package, and a set
of @arguments passed to the package to generate a new
$variant_package , which will be returned.
use Package::Variant @options;
Sets up the environment in which you declare the variants of your
packages. See OPTIONS for details on the available options and
EXPORTS for a list of exported subroutines.
Additionally to the proxies for subroutines provided in subs, the
following exports will be available in your variable package:
install($method_name, $code_reference);
Installs a method with the given $method_name into the newly created
variant package. The $code_reference will be used as the body for the
method, and if the Sub::Name manpage is available the coderef will be named. If you
want to name it something else, then use:
install($method_name, $name_to_use, $code_reference);
mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
Copyright (c) 2010-2012 the Package::Variant AUTHOR and
CONTRIBUTORS as listed above.
This library is free software and may be distributed under the same
terms as perl itself.
|