=head1 SYNOPSIS
# declaring a variable Moo role
- package My::Role::ObjectAttr;
+ package My::VariableRole::ObjectAttr;
use strictures 1;
use Package::Variant
# what modules to 'use'
package My::Class::WithObjectAttr;
use strictures 1;
use Moo;
- use My::Role::ObjectAttr;
+ use My::VariableRole::ObjectAttr;
with ObjectAttr(name => 'some_obj', class => 'Some::Class');
=head1 DESCRIPTION
-This module allows you to build packages that return different variations
-depending on what parameters are given.
+This module allows you to build a variable package that returns different
+variant packages depending on what parameters are given.
-Users of your package will receive a subroutine able to take parameters
+Users of your variable package will receive a subroutine able to take parameters
and return the name of a suitable variant package. The implementation does
-not care about what kind of package it builds.
+not care about what kind of variant package it builds.
=head2 Declaring a variable package
There are two important parts to creating a variable package. You first
have to give C<Package::Variant> some basic information about what kind of
-package you want to provide, and how. The second part is implementing a
-method receiving the user's arguments and generating your variants.
+variant packages you want to provide, and how. The second part is implementing a
+method receiving the user's arguments and generating your variant packages.
-=head3 Setting up the environment for building variations
+=head3 Setting up the environment for building variants
When you C<use Package::Variant>, you pass along some arguments that
-describe how you intend to build your variations.
+describe how you intend to build your variants.
use Package::Variant
importing => { $package => \@import_arguments, ... },
The L</importing> option needs to be a hash or array reference with
package names to be C<use>d as keys, and array references containing the
import arguments as values. These packages will be imported into every new
-variant, and need to set up every declarative subroutine you require to
+variant package, and need to set up every declarative subroutine you require to
build your variable package. The next option will allow you to use these
functions. See L</importing> for more options. You can omit empty import
argument lists when passing an array reference.
The L</subs> option is an array reference of subroutine names that are
exported by the packages specified with L</importing>. These subroutines
-will be proxied from your declaration package to the variant to be
+will be proxied from your variable package to the variant to be
generated.
With L</importing> initializing your package and L</subs> declaring what
the user.
It can then use the proxied subroutines declared with L</subs> to
-customize the new package. An L</install> subroutine is exported as well
-allowing you to dynamically install methods into the new package. If these
-options aren't flexible enough, you can use the passed name of the new
+customize the variant package. An L</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 {
# ...
}
-When the method is finished, the user will receive the name of the new
-package variant you just set up.
+When the method is finished, the user will receive the name of the new variant
+package you just set up.
=head2 Using variable packages
use My::Variant;
my $new_variant_package = Variant(@variant_arguments);
+ # the variant package is now fully initialized and used
-The package is now fully initialized and used. You can import the
-subroutine under a different name by specifying an C<as> argument.
+You can import the subroutine under a different name by specifying an C<as>
+argument.
=head2 Dynamic creation of variant packages
For regular uses, the L<normal import|/Using variable packages> provides
-more than enough flexibility. However, if you want to create variations of
+more than enough flexibility. However, if you want to create variants of
dynamically determined packages, you can use the L</build_variant_of>
method.
-You can use this to create variations of other packages and pass arguments
-on to them to allow more modular and extensible variations.
+You can use this to create variants of other packages and pass arguments
+on to them to allow more modular and extensible variants.
=head1 OPTIONS
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 variation before the L</make_variant> method is asked
+arguments by every variant before the L</make_variant> method is asked
to create the package (this is done using L<Import::Into>).
If import order is important to you, you can also pass the C<importing>
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 L</importing>. Subroutines
-with the same name will be available in your declaration package, and will
+with the same name will be available in your variable package, and will
proxy through to the newly created package when used within
L</make_variant>.
projects / p5sagit/Package-Variant.git / commitdiff