1 package Package::Variant;
5 use Module::Runtime qw(use_module);
8 our $VERSION = '1.001001'; # 1.1.1
10 $VERSION = eval $VERSION;
14 my $sanitize_importing = sub {
21 : (ref($spec) eq 'ARRAY')
23 : (ref($spec) eq 'HASH')
25 croak qq{The import argument list for '$_' is not an array ref}
26 unless ref($spec->{$_}) eq 'ARRAY';
29 : croak q{The 'importing' option has to be either a hash or array ref};
33 my $key = shift @specced;
34 croak qq{Value $arg_count in 'importing' is not a package string},
36 unless defined($key) and not(ref $key);
39 (not(@specced) or (defined($specced[0]) and not ref($specced[0])))
41 : (ref($specced[0]) eq 'ARRAY')
42 ? do { $arg_count++; shift @specced }
44 qq{Value $arg_count for package '$key' in 'importing' is not}
45 . qq{ a package string or array ref}
47 push @imports, [$key, $import_args];
52 my $sub_namer = eval {
53 require Sub::Name; sub { shift if @_ > 2; Sub::Name::subname(@_) }
59 my $last = (split '::', $target)[-1];
61 my $variable = $target;
64 $Variable{$variable} = {
67 make_variant => 'make_variant',
69 importing => $me->$sanitize_importing($args{importing}),
72 map +($_ => sub {}), @{$args{subs}||[]},
75 *{"${target}::import"} = sub {
77 my (undef, %arg) = @_;
78 my $as = defined($arg{as}) ? $arg{as} : $last;
80 *{"${target}::${as}"} = sub {
81 $me->build_variant_of($variable, @_);
83 } unless $args{no_import};
84 my $subs = $Variable{$variable}{subs};
85 foreach my $name (keys %$subs) {
86 *{"${target}::${name}"} = sub {
87 goto &{$subs->{$name}}
90 *{"${target}::install"} = sub {
91 goto &{$Variable{$variable}{install}};
95 sub build_variant_of {
96 my ($me, $variable, @args) = @_;
97 my $variant_name = "${variable}::_Variant_".++$Variable{$variable}{anon};
98 foreach my $to_import (@{$Variable{$variable}{args}{importing}}) {
99 my ($pkg, $args) = @$to_import;
100 use_module($pkg)->import::into($variant_name, @{$args});
102 my $subs = $Variable{$variable}{subs};
103 local @{$subs}{keys %$subs} = map $variant_name->can($_), keys %$subs;
104 local $Variable{$variable}{install} = sub {
105 my $full_name = "${variant_name}::".shift;
107 my $ref = $sub_namer->($full_name, @_);
112 $variable->${\$Variable{$variable}{args}{make_variant}}($variant_name, @args);
113 return $variant_name;
122 Package::Variant - Parameterizable packages
126 # declaring a variable Moo role
127 package My::Role::ObjectAttr;
130 # what modules to 'use'
131 importing => ['Moo::Role'],
132 # proxied subroutines
133 subs => [ qw(has around before after with) ],
136 my ($class, $target_package, %arguments) = @_;
138 my $name = $arguments{name};
139 # use proxied 'has' to add an attribute
140 has $name => (is => 'lazy');
141 # install a builder method
142 install "_build_${name}" => sub {
143 return $arguments{class}->new;
148 package My::Class::WithObjectAttr;
151 use My::Role::ObjectAttr;
153 with ObjectAttr(name => 'some_obj', class => 'Some::Class');
156 my $obj = My::Class::WithObjectAttr->new;
157 $obj->some_obj; # returns a Some::Class instance
161 This module allows you to build packages that return different variations
162 depending on what parameters are given.
164 Users of your package will receive a subroutine able to take parameters
165 and return the name of a suitable variant package. The implmenetation does
166 not care about what kind of package it builds.
168 =head2 Declaring a variable package
170 There are two important parts to creating a variable package. You first
171 have to give C<Package::Variant> some basic information about what kind of
172 package you want to provide, and how. The second part is implementing a
173 method receiving the user's arguments and generating your variants.
175 =head3 Setting up the environment for building variations
177 When you C<use Package::Variant>, you pass along some arguments that
178 describe how you intend to build your variations.
181 importing => { $package => \@import_arguments, ... },
182 subs => [ @proxied_subroutine_names ];
184 The L</importing> option needs to be a hash or array reference with
185 package names to be C<use>d as keys, and array references containing the
186 import arguments as values. These packages will be imported into every new
187 variant, and need to set up every declarative subroutine you require to
188 build your variable package. The next option will allow you to use these
189 functions. See L</importing> for more options. You can omit empty import
190 argument lists when passing an array reference.
192 The L</subs> option is an array reference of subroutine names that are
193 exported by the packages specified with L</importing>. These subroutines
194 will be proxied from your declaration package to the variant to be
197 With L</importing> initializing your package and L</subs> declaring what
198 subroutines you want to use to build a variant, you can now write a
199 L</make_variant> method building your variants.
201 =head3 Declaring a method to produce variants
203 Every time a user requests a new variant a method named L</make_variant>
204 will be called with the name of the target package and the arguments from
207 It can then use the proxied subroutines declared with L</subs> to
208 customize the new package. An L</install> subroutine is exported as well
209 allowing you to dynamically install methods into the new package. If these
210 options aren't flexible enough, you can use the passed name of the new
211 package to do any other kind of customizations.
214 my ($class, $target, @arguments) = @_;
216 # customization goes here
220 When the method is finished, the user will receive the name of the new
221 package variant you just set up.
223 =head2 Using variable packages
225 After your variable package is L<created|/Declaring a variable package>
226 your users can get a variant generating subroutine by simply importing
230 my $new_variant_package = Variant(@variant_arguments);
232 The package is now fully initialized and used. You can import the
233 subroutine under a different name by specifying an C<as> argument.
235 =head2 Dynamic creation of variant packages
237 For regular uses, the L<normal import|/Using variable packages> provides
238 more than enough flexibility. However, if you want to create variations of
239 dynamically determined packages, you can use the L</build_variation_of>
242 You can use this to create variations of other packages and pass arguments
243 on to them to allow more modular and extensible variations.
247 These are the options that can be passed when importing
248 C<Package::Variant>. They describe the environment in which the variants
252 importing => { $package => \@import_arguments, ... },
253 subs => [ @proxied_subroutines ];
257 This option is a hash reference mapping package names to array references
258 containing import arguments. The packages will be imported with the given
259 arguments by every variation before the L</make_variant> method is asked
260 to create the package (this is done using L<Import::Into>).
262 If import order is important to you, you can also pass the C<importing>
263 arguments as a flat array reference:
266 importing => [ 'PackageA', 'PackageB' ];
270 importing => [ 'PackageA' => [], 'PackageB' => [] ];
274 importing => { 'PackageA' => [], 'PackageB' => [] };
276 The import method will be called even if the list of import arguments is
277 empty or not specified,
279 If you just want to import a single package's default exports, you can
280 also pass a string instead:
282 use Package::Variant importing => 'Package';
286 An array reference of strings listing the names of subroutines that should
287 be proxied. These subroutines are expected to be installed into the new
288 variant package by the modules imported with L</importing>. Subroutines
289 with the same name will be availabe in your declaration package, and will
290 proxy through to the newly created package when used within
293 =head1 VARIABLE PACKAGE METHODS
295 These are methods on the variable package you declare when you import
300 Some::Variant::Package->make_variant( $target, @arguments );
302 B<You need to provide this method.> This method will be called for every
303 new variant of your package. This method should use the subroutines
304 declared in L</subs> to customize the new variant package.
306 This is a class method receiving the C<$target> package and the
307 C<@arguments> defining the requested variant.
311 use Some::Variant::Package;
312 my $variant_package = Package( @arguments );
314 This method is provided for you. It will allow a user to C<use> your
315 package and receive a subroutine taking C<@arguments> defining the variant
316 and returning the name of the newly created variant package.
318 The following options can be specified when importing:
324 use Some::Variant::Package as => 'Foo';
325 my $variant_package = Foo(@arguments);
327 Exports the generator subroutine under a different name than the default.
331 =head1 C<Package::Variant> METHODS
333 These methods are available on C<Package::Variant> itself.
335 =head2 build_variation_of
337 my $variant_package = Package::Variant
338 ->build_variation_of($variable_package, @arguments);
340 This is the dynamic method of creating new variants. It takes the
341 C<$variable_package>, which is a pre-declared variable package, and a set
342 of C<@arguments> passed to the package to generate a new
343 C<$variant_package>, which will be returned.
347 use Package::Variant @options;
349 Sets up the environment in which you declare the variants of your
350 packages. See L</OPTIONS> for details on the available options and
351 L</EXPORTS> for a list of exported subroutines.
355 Additionally to the proxies for subroutines provided in L</subs>, the
356 following exports will be available in your variable package:
360 install($method_name, $code_reference);
362 Installs a method with the given C<$method_name> into the newly created
363 variant package. The C<$code_reference> will be used as the body for the
364 method, and if L<Sub::Name> is available the coderef will be named. If you
365 want to name it something else, then use:
367 install($method_name, $name_to_use, $code_reference);
371 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
375 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
379 Copyright (c) 2010-2012 the C<Package::Variant> L</AUTHOR> and
380 L</CONTRIBUTORS> as listed above.
384 This library is free software and may be distributed under the same
385 terms as perl itself.