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.

The "importing" option needs to be a hash or array reference with package names to be used 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.

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:

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.

build_variant

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

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: