1 package Package::Variant;
10 my $last = (split '::', $target)[-1];
12 my $variable = $target;
15 $Variable{$variable} = {
19 map +($_ => sub {}), @{$args{subs}||[]},
22 *{"${target}::import"} = sub {
25 *{"${target}::${last}"} = sub {
26 $me->build_variant_of($variable, @_);
29 my $subs = $Variable{$variable}{subs};
30 foreach my $name (keys %$subs) {
31 *{"${target}::${name}"} = sub {
32 goto &{$subs->{$name}}
35 *{"${target}::install"} = sub {
36 goto &{$Variable{$variable}{install}};
40 sub build_variant_of {
41 my ($me, $variable, @args) = @_;
42 my $variant_name = "${variable}::_Variant_".++$Variable{$variable}{anon};
43 my @to_import = keys %{$Variable{$variable}{args}{importing}||{}};
44 my $setup = join("\n", "package ${variant_name};", (map "use $_;", @to_import), "1;");
46 or die "evaling ${setup} failed: $@";
47 my $subs = $Variable{$variable}{subs};
48 local @{$subs}{keys %$subs} = map $variant_name->can($_), keys %$subs;
49 local $Variable{$variable}{install} = sub {
50 my ($name, $ref) = @_;
52 *{"${variant_name}::${name}"} = $ref;
54 $variable->make_variant($variant_name, @args);
64 Package::Variant - Parameterizable packages
68 # declaring a variable Moo role
69 package My::Role::ObjectAttr;
72 # what modules to 'use'
73 importing => { 'Moo::Role' => [] },
75 subs => [qw( has around before after extends )],
78 my ($class, $target_package, %arguments) = @_;
80 my $name = $arguments{name};
81 # use proxied 'has' to add an attribute
82 has $name => (is => 'lazy');
83 # install a builder method
84 install "_build_${name}" => sub {
85 return $arguments{class}->new;
90 package My::Class::WithObjectAttr;
93 use My::Role::ObjectAttr;
95 with ObjectAttr(name => 'some_obj', class => 'Some::Class');
98 my $obj = My::Class::WithObjectAttr->new;
99 $obj->some_obj; # returns a Some::Class instance
103 This module allows you to build packages that return different variations
104 depending on what parameters are given.
106 Users of your package will receive a subroutine able to take parameters
107 and return the name of a suitable variant package. The implmenetation does
108 not care about what kind of package it builds.
110 =head2 Declaring a variable package
112 There are two important parts to creating a variable package. You first
113 have to give C<Package::Variant> some basic information about what kind of
114 package you want to provide, and how. The second part is implementing a
115 method receiving the user's arguments and generating your variants.
117 =head3 Setting up the environment for building variations
119 When you C<use Package::Variant>, you pass along some arguments that
120 describe how you intend to build your variations.
123 importing => { $package => \@import_arguments, ... },
124 subs => [ @proxied_subroutine_names ];
126 The L</importing> option needs to be a hash reference with package names
127 to be C<use>d as keys, and array references containing the import
128 arguments as values. These packages will be imported into every new
129 variant, and need to set up every declarative subroutine you require to
130 build your variable package. The next option will allow you to use these
133 The L</subs> option is an array reference of subroutine names that are
134 exported by the packages specified with L</importing>. These subroutines
135 will be proxied from your declaration package to the variant to be
138 With L</importing> initializing your package and L</subs> declaring what
139 subroutines you want to use to build a variant, you can now write a
140 L</make_variant> method building your variants.
142 =head3 Declaring a method to produce variants
144 Every time a user requests a new variant a method named L</make_variant>
145 will be called with the name of the target package and the arguments from
148 It can then use the proxied subroutines declared with L</subs> to
149 customize the new package. An L</install> subroutine is exported as well
150 allowing you to dynamically install methods into the new package. If these
151 options aren't flexible enough, you can use the passed name of the new
152 package to do any other kind of customizations.
155 my ($class, $target, @arguments) = @_;
157 # customization goes here
161 When the method is finished, the user will receive the name of the new
162 package variant you just set up.
164 =head2 Using variable packages
166 After your variable package is L<created|/Declaring a variable package>
167 your users can get a variant generating subroutine by simply importing
171 my $new_variant_package = Variant( @variant_arguments );
173 The package is now fully initialized and used.
175 =head2 Dynamic creation of variant packages
177 For regular uses, the L<normal import|/Using variable packages> provides
178 more than enough flexibility. However, if you want to create variations of
179 dynamically determined packages, you can use the L</build_variation_of>
182 You can use this to create variations of other packages and pass arguments
183 on to them to allow more modular and extensible variations.
187 These are the options that can be passed when importing
188 C<Package::Variant>. They describe the environment in which the variants
192 importing => { $package => \@import_arguments, ... },
193 subs => [ @proxied_subroutines ];
197 This option is a hash reference mapping package names to array references
198 containing import arguments. The packages will be C<use>d with the given
199 arguments by every variation before the L</make_variant> method is asked
200 to create the package.
204 An array reference of strings listing the names of subroutines that should
205 be proxied. These subroutines are expected to be installed into the new
206 variant package by the modules imported with L</importing>. Subroutines
207 with the same name will be availabe in your declaration package, and will
208 proxy through to the newly created package when used within
211 =head1 VARIABLE PACKAGE METHODS
213 These are methods on the variable package you declare when you import
218 Some::Variant::Package->make_variant( $target, @arguments );
220 B<You need to provide this method.> This method will be called for every
221 new variant of your package. This method should use the subroutines
222 declared in L</subs> to customize the new variant package.
224 This is a class method receiving the C<$target> package and the
225 C<@arguments> defining the requested variant.
229 use Some::Variant::Package;
230 my $variant_package = Package( @arguments );
232 This method is provided for you. It will allow a user to C<use> your
233 package and receive a subroutine taking C<@arguments> defining the variant
234 and returning the name of the newly created variant package.
236 =head1 C<Package::Variant> METHODS
238 These methods are available on C<Package::Variant> itself.
240 =head2 build_variation_of
242 my $variant_package = Package::Variant
243 ->build_variation_of( $variable_package, @arguments );
245 This is the dynamic method of creating new variants. It takes the
246 C<$variable_package>, which is a pre-declared variable package, and a set
247 of C<@arguments> passed to the package to generate a new
248 C<$variant_package>, which will be returned.
252 use Package::Variant @options;
254 Sets up the environment in which you declare the variants of your
255 packages. See L</OPTIONS> for details on the available options and
256 L</EXPORTS> for a list of exported subroutines.
260 Additionally to the proxies for subroutines provided in L</subs>, the
261 following exports will be available in your variable package:
265 install( $method_name, $code_reference );
267 Installs a method with the given C<$method_name> into the newly created
268 variant package. The C<$code_reference> will be used as the body for the
275 =item mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
281 Copyright (c) 2010-2011 the C<Package::Stash> L</AUTHOR> as listed above.
285 This library is free software and may be distributed under the same
286 terms as perl itself.