NAME
   Package::Variant - Parameterizable packages

SYNOPSIS
   Creation of anonymous variants:

     # declaring a variable Moo role
     package My::VariableRole::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::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 1;
     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 1;
     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

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

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

  Setting up the environment for building variants
   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.

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

 Using variable packages
   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.

 Dynamic creation of variant packages
   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.

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 variant 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 variable
   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.

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

 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) <[email protected]>

CONTRIBUTORS
   phaylon - Robert Sedlacek (cpan:PHAYLON) <[email protected]>

   haarg - Graham Knop (cpan:HAARG) <[email protected]>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.