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 implementation
    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 available 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.

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

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