NAME

       Package::Variant - Parameterizable packages

SYNOPSIS

         # declaring a variable Moo role
         package My::Role::ObjectAttr;
         use strictures 1;
         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 1;
         use Moo;
         use My::Role::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

DESCRIPTION

       This module allows you to build packages that return different variations depending on
       what parameters are given.

       Users of your package will receive a subroutine able to take parameters and return the
       name of a suitable variant package. The implmenetation does not care about what kind of
       package it builds.

   Declaring a variable package
       There are two important parts to creating a variable package. You first have to give
       "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.

       Setting up the environment for building variations

       When you "use Package::Variant", you pass along some arguments that describe how you
       intend to build your variations.

         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, 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 "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
       declaration 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.

       Declaring a method to produce 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 new package.
       An "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 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 package variant you
       just set up.

   Using variable packages
       After your variable package is created your users can get a variant generating subroutine
       by simply importing your package.

         use My::Variant;
         my $new_variant_package = Variant(@variant_arguments);

       The package is now fully initialized and used. You can import the subroutine under a
       different name by specifying an "as" argument.

   Dynamic creation of variant packages
       For regular uses, the normal import provides more than enough flexibility. However, if you
       want to create variations of dynamically determined packages, you can use the
       "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.

OPTIONS

       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 ];

   importing
       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 "make_variant" method is asked to create the package (this is done
       using Import::Into).

       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';

   subs
       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 availabe in your
       declaration package, and will proxy through to the newly created package when used within
       "make_variant".

VARIABLE PACKAGE METHODS

       These are methods on the variable package you declare when you import "Package::Variant".

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

   import
         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:

       •   as

             use Some::Variant::Package as => 'Foo';
             my $variant_package = Foo(@arguments);

           Exports the generator subroutine under a different name than the default.

"Package::Variant" METHODS

       These methods are available on "Package::Variant" itself.

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

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

EXPORTS

       Additionally to the proxies for subroutines provided in "subs", the following exports will
       be available in your variable package:

   install
         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 Sub::Name 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);

AUTHOR

       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>

CONTRIBUTORS

       phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>

COPYRIGHT

       Copyright (c) 2010-2012 the "Package::Variant" "AUTHOR" and "CONTRIBUTORS" as listed
       above.

LICENSE

       This library is free software and may be distributed under the same terms as perl itself.