[libpackage-variant-perl] 14/23: Imported Upstream version 1.003002
Jonas Smedegaard
dr at jones.dk
Tue Aug 4 13:25:45 UTC 2015
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 <dr at 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) <mst at 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-Variant at 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) <mst at 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) <mst at shadowcat.co.uk>
+
+CONTRIBUTORS
+ phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek at shadowcat.co.uk>
+
+ haarg - Graham Knop (cpan:HAARG) <haarg at 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
More information about the Pkg-perl-cvs-commits
mailing list