This is an automated email from the git hooks/post-receive script. js pushed a commit to branch master in repository libpackage-variant-perl.
commit 4a8ea6d4cdcffa258863be7cb9ef2d66b2e35245 Merge: c9d6629 6d52bb4 Author: Jonas Smedegaard <d...@jones.dk> Date: Tue Aug 4 15:09:06 2015 +0200 Imported Upstream version 1.003002 Changes | 10 ++++++ META.json | 8 ++--- META.yml | 8 ++--- Makefile.PL | 10 +++--- README | 63 ++++++++++++++++++++++++++++++++++++-- lib/Package/Variant.pm | 77 ++++++++++++++++++++++++++++++++++++++++++++--- maint/Makefile.PL.include | 1 + t/01simple.t | 21 ++++++++++++- t/10argument-types.t | 2 +- t/11dynamic-build.t | 2 +- t/20moo-param-role.t | 2 +- t/30-pragma-leak.t | 2 +- 12 files changed, 181 insertions(+), 25 deletions(-) diff --cc META.json index 8abd1a4,0000000..908f2c2 mode 100644,000000..100644 --- a/META.json +++ b/META.json @@@ -1,56 -1,0 +1,56 @@@ +{ + "abstract" : "Parameterizable packages", + "author" : [ + "mst - Matt S. Trout (cpan:MSTROUT) <m...@shadowcat.co.uk>" + ], + "dynamic_config" : 0, - "generated_by" : "ExtUtils::MakeMaker version 6.98, CPAN::Meta::Converter version 2.141520", ++ "generated_by" : "ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.150001", + "license" : [ + "perl_5" + ], + "meta-spec" : { + "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", + "version" : "2" + }, + "name" : "Package-Variant", + "no_index" : { + "directory" : [ + "t", + "xt" + ], + "package" : [ + "string" + ] + }, + "prereqs" : { + "build" : {}, + "configure" : {}, + "runtime" : { + "requires" : { + "Carp" : "0", - "Import::Into" : "1", ++ "Import::Into" : "1.000000", + "Module::Runtime" : "0.013", + "perl" : "5.006", - "strictures" : "1" ++ "strictures" : "2.000000" + } + }, + "test" : { + "requires" : { + "Test::Fatal" : "0" + } + } + }, + "release_status" : "stable", + "resources" : { + "bugtracker" : { + "mailto" : "bug-package-vari...@rt.cpan.org", + "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=Package-Variant" + }, + "repository" : { + "type" : "git", + "url" : "git://git.shadowcat.co.uk/p5sagit/Package-Variant.git", + "web" : "http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Package-Variant.git" + } + }, - "version" : "1.002002" ++ "version" : "1.003002" +} diff --cc META.yml index 28d2fe5,0000000..c0f6bf5 mode 100644,000000..100644 --- a/META.yml +++ b/META.yml @@@ -1,29 -1,0 +1,29 @@@ +--- +abstract: 'Parameterizable packages' +author: + - 'mst - Matt S. Trout (cpan:MSTROUT) <m...@shadowcat.co.uk>' +build_requires: + Test::Fatal: '0' +dynamic_config: 0 - generated_by: 'ExtUtils::MakeMaker version 6.98, CPAN::Meta::Converter version 2.141520' ++generated_by: 'ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.150001' +license: perl +meta-spec: + url: http://module-build.sourceforge.net/META-spec-v1.4.html + version: '1.4' +name: Package-Variant +no_index: + directory: + - t + - xt + package: + - string +requires: + Carp: '0' - Import::Into: '1' ++ Import::Into: '1.000000' + Module::Runtime: '0.013' + perl: '5.006' - strictures: '1' ++ strictures: '2.000000' +resources: + bugtracker: https://rt.cpan.org/Public/Dist/Display.html?Name=Package-Variant + repository: git://git.shadowcat.co.uk/p5sagit/Package-Variant.git - version: '1.002002' ++version: '1.003002' diff --cc README index 649c965,0000000..4a44f8b mode 100644,000000..100644 --- a/README +++ b/README @@@ -1,257 -1,0 +1,316 @@@ +NAME + Package::Variant - Parameterizable packages + +SYNOPSIS ++ Creation of anonymous variants: ++ + # declaring a variable Moo role + package My::VariableRole::ObjectAttr; - use strictures 1; ++ use strictures 2; + 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 strictures 2; + 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 2; ++ 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 2; ++ 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) <m...@shadowcat.co.uk> + +CONTRIBUTORS + phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedla...@shadowcat.co.uk> + + haarg - Graham Knop (cpan:HAARG) <ha...@haarg.org> + +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. + -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libpackage-variant-perl.git _______________________________________________ Pkg-perl-cvs-commits mailing list Pkg-perl-cvs-commits@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits