1 package Package::Variant;
6 our $VERSION = '1.000000'; # 1.0.0
8 $VERSION = eval $VERSION;
12 my $sanitize_importing = sub {
19 : (ref($spec) eq 'ARRAY')
21 : (ref($spec) eq 'HASH')
23 croak qq{The import argument list for '$_' is not an array ref}
24 unless ref($spec->{$_}) eq 'ARRAY';
27 : croak q{The 'importing' option has to be either a hash or array ref};
31 my $key = shift @specced;
32 croak qq{Value $arg_count in 'importing' is not a package string},
34 unless defined($key) and not(ref $key);
37 (not(@specced) or (defined($specced[0]) and not ref($specced[0])))
39 : (ref($specced[0]) eq 'ARRAY')
40 ? do { $arg_count++; shift @specced }
42 qq{Value $arg_count for package '$key' in 'importing' is not}
43 . qq{ a package string or array ref}
45 push @imports, [$key, $import_args];
50 my $sub_namer = eval {
51 require Sub::Name; sub { shift if @_ > 2; Sub::Name::subname(@_) }
57 my $last = (split '::', $target)[-1];
59 my $variable = $target;
62 $Variable{$variable} = {
66 importing => $me->$sanitize_importing($args{importing}),
69 map +($_ => sub {}), @{$args{subs}||[]},
72 *{"${target}::import"} = sub {
74 my (undef, %arg) = @_;
75 my $as = defined($arg{as}) ? $arg{as} : $last;
77 *{"${target}::${as}"} = sub {
78 $me->build_variant_of($variable, @_);
81 my $subs = $Variable{$variable}{subs};
82 foreach my $name (keys %$subs) {
83 *{"${target}::${name}"} = sub {
84 goto &{$subs->{$name}}
87 *{"${target}::install"} = sub {
88 goto &{$Variable{$variable}{install}};
92 sub build_variant_of {
93 my ($me, $variable, @args) = @_;
94 my $variant_name = "${variable}::_Variant_".++$Variable{$variable}{anon};
95 my $import = $Variable{$variable}{args}{importing};
96 my $setup = join("\n",
97 "package ${variant_name};",
101 scalar(@{$import->[$_][1]})
103 q!@{$import->[%d][1]}!,
111 or die "evaling ${setup} failed: $@";
112 my $subs = $Variable{$variable}{subs};
113 local @{$subs}{keys %$subs} = map $variant_name->can($_), keys %$subs;
114 local $Variable{$variable}{install} = sub {
115 my $full_name = "${variant_name}::".shift;
117 my $ref = $sub_namer->($full_name, @_);
122 $variable->make_variant($variant_name, @args);
123 return $variant_name;
132 Package::Variant - Parameterizable packages
136 # declaring a variable Moo role
137 package My::Role::ObjectAttr;
140 # what modules to 'use'
141 importing => ['Moo::Role'],
142 # proxied subroutines
143 subs => [qw( has around before after extends )],
146 my ($class, $target_package, %arguments) = @_;
148 my $name = $arguments{name};
149 # use proxied 'has' to add an attribute
150 has $name => (is => 'lazy');
151 # install a builder method
152 install "_build_${name}" => sub {
153 return $arguments{class}->new;
158 package My::Class::WithObjectAttr;
161 use My::Role::ObjectAttr;
163 with ObjectAttr(name => 'some_obj', class => 'Some::Class');
166 my $obj = My::Class::WithObjectAttr->new;
167 $obj->some_obj; # returns a Some::Class instance
171 This module allows you to build packages that return different variations
172 depending on what parameters are given.
174 Users of your package will receive a subroutine able to take parameters
175 and return the name of a suitable variant package. The implmenetation does
176 not care about what kind of package it builds.
178 =head2 Declaring a variable package
180 There are two important parts to creating a variable package. You first
181 have to give C<Package::Variant> some basic information about what kind of
182 package you want to provide, and how. The second part is implementing a
183 method receiving the user's arguments and generating your variants.
185 =head3 Setting up the environment for building variations
187 When you C<use Package::Variant>, you pass along some arguments that
188 describe how you intend to build your variations.
191 importing => { $package => \@import_arguments, ... },
192 subs => [ @proxied_subroutine_names ];
194 The L</importing> option needs to be a hash or array reference with
195 package names to be C<use>d as keys, and array references containing the
196 import arguments as values. These packages will be imported into every new
197 variant, and need to set up every declarative subroutine you require to
198 build your variable package. The next option will allow you to use these
199 functions. See L</importing> for more options. You can omit empty import
200 argument lists when passing an array reference.
202 The L</subs> option is an array reference of subroutine names that are
203 exported by the packages specified with L</importing>. These subroutines
204 will be proxied from your declaration package to the variant to be
207 With L</importing> initializing your package and L</subs> declaring what
208 subroutines you want to use to build a variant, you can now write a
209 L</make_variant> method building your variants.
211 =head3 Declaring a method to produce variants
213 Every time a user requests a new variant a method named L</make_variant>
214 will be called with the name of the target package and the arguments from
217 It can then use the proxied subroutines declared with L</subs> to
218 customize the new package. An L</install> subroutine is exported as well
219 allowing you to dynamically install methods into the new package. If these
220 options aren't flexible enough, you can use the passed name of the new
221 package to do any other kind of customizations.
224 my ($class, $target, @arguments) = @_;
226 # customization goes here
230 When the method is finished, the user will receive the name of the new
231 package variant you just set up.
233 =head2 Using variable packages
235 After your variable package is L<created|/Declaring a variable package>
236 your users can get a variant generating subroutine by simply importing
240 my $new_variant_package = Variant( @variant_arguments );
242 The package is now fully initialized and used. You can import the
243 subroutine under a different name by specifying an C<as> argument.
245 =head2 Dynamic creation of variant packages
247 For regular uses, the L<normal import|/Using variable packages> provides
248 more than enough flexibility. However, if you want to create variations of
249 dynamically determined packages, you can use the L</build_variation_of>
252 You can use this to create variations of other packages and pass arguments
253 on to them to allow more modular and extensible variations.
257 These are the options that can be passed when importing
258 C<Package::Variant>. They describe the environment in which the variants
262 importing => { $package => \@import_arguments, ... },
263 subs => [ @proxied_subroutines ];
267 This option is a hash reference mapping package names to array references
268 containing import arguments. The packages will be C<use>d with the given
269 arguments by every variation before the L</make_variant> method is asked
270 to create the package.
272 If import order is important to you, you can also pass the C<importing>
273 arguments as a flat array reference:
276 importing => [ 'PackageA', 'PackageB' ];
280 importing => [ 'PackageA' => [], 'PackageB' => [] ];
284 importing => { 'PackageA' => [], 'PackageB' => [] };
286 The import method will be called even if the list of import arguments is
287 empty or not specified,
289 If you just want to import a single package's default exports, you can
290 also pass a string instead:
292 use PAckage::Variant importing => 'Package';
296 An array reference of strings listing the names of subroutines that should
297 be proxied. These subroutines are expected to be installed into the new
298 variant package by the modules imported with L</importing>. Subroutines
299 with the same name will be availabe in your declaration package, and will
300 proxy through to the newly created package when used within
303 =head1 VARIABLE PACKAGE METHODS
305 These are methods on the variable package you declare when you import
310 Some::Variant::Package->make_variant( $target, @arguments );
312 B<You need to provide this method.> This method will be called for every
313 new variant of your package. This method should use the subroutines
314 declared in L</subs> to customize the new variant package.
316 This is a class method receiving the C<$target> package and the
317 C<@arguments> defining the requested variant.
321 use Some::Variant::Package;
322 my $variant_package = Package( @arguments );
324 This method is provided for you. It will allow a user to C<use> your
325 package and receive a subroutine taking C<@arguments> defining the variant
326 and returning the name of the newly created variant package.
328 The following options can be specified when importing:
334 use Some::Variant::Package as => 'Foo';
335 my $variant_package = Foo( @arguments );
337 Exports the generator subroutine under a different name than the default.
341 =head1 C<Package::Variant> METHODS
343 These methods are available on C<Package::Variant> itself.
345 =head2 build_variation_of
347 my $variant_package = Package::Variant
348 ->build_variation_of( $variable_package, @arguments );
350 This is the dynamic method of creating new variants. It takes the
351 C<$variable_package>, which is a pre-declared variable package, and a set
352 of C<@arguments> passed to the package to generate a new
353 C<$variant_package>, which will be returned.
357 use Package::Variant @options;
359 Sets up the environment in which you declare the variants of your
360 packages. See L</OPTIONS> for details on the available options and
361 L</EXPORTS> for a list of exported subroutines.
365 Additionally to the proxies for subroutines provided in L</subs>, the
366 following exports will be available in your variable package:
370 install( $method_name, $code_reference );
372 Installs a method with the given C<$method_name> into the newly created
373 variant package. The C<$code_reference> will be used as the body for the
378 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
382 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
386 Copyright (c) 2010-2011 the C<Package::Variant> L</AUTHOR> and
387 L</CONTRIBUTORS> as listed above.
391 This library is free software and may be distributed under the same
392 terms as perl itself.