From: Paul Driver Date: Fri, 11 Apr 2008 14:25:09 +0000 (+0000) Subject: Some more documentation updates. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=f2b3b8f9c6a8ae45724219fe12a0961790803f07;p=gitmo%2FMooseX-AttributeHelpers.git Some more documentation updates. --- diff --git a/lib/MooseX/AttributeHelpers.pm b/lib/MooseX/AttributeHelpers.pm index 8434aeb..0d2b8bc 100644 --- a/lib/MooseX/AttributeHelpers.pm +++ b/lib/MooseX/AttributeHelpers.pm @@ -109,6 +109,13 @@ The methods provided by the above methods can be selectively composed with the metaclass L, which is also available in L form. +=head1 METHOD PROVIDERS + +There is an interface for defining new MethodProviders that can be used either +directly by L or by a custom +metaclass that you create (see L). The +interface is defined by L. + =head1 CAVEAT This is an early release of this module. Right now it is in great need @@ -146,6 +153,8 @@ Tom (dec) Lanyon Yuval Kogman +Paul (frodwith) Driver + =head1 COPYRIGHT AND LICENSE Copyright 2007, 2008 by Infinity Interactive, Inc. diff --git a/lib/MooseX/AttributeHelpers/Composite.pm b/lib/MooseX/AttributeHelpers/Composite.pm index 001803c..dc2a3b9 100644 --- a/lib/MooseX/AttributeHelpers/Composite.pm +++ b/lib/MooseX/AttributeHelpers/Composite.pm @@ -11,3 +11,29 @@ package # Over there, search.cpan! Run! Fetch! sub register_implementation { 'MooseX::AttributeHelpers::Composite' } 1; + +__END__ + +=pod + +=head1 NAME + +MooseX::AttributeHelpers::Composite + +=head1 DESCRIPTION + +This is just a metaclass that consumes the L. It also registers a +shortcut for itself under the name "Composite". + +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. If you find a bug please either email me, or add the bug +to cpan-RT. + +=head1 AUTHOR + +Paul Driver Efrodwith@cpan.orgE + +=cut diff --git a/lib/MooseX/AttributeHelpers/Composite/Trait.pm b/lib/MooseX/AttributeHelpers/Composite/Trait.pm index 634f2b9..1a75d47 100644 --- a/lib/MooseX/AttributeHelpers/Composite/Trait.pm +++ b/lib/MooseX/AttributeHelpers/Composite/Trait.pm @@ -42,3 +42,88 @@ after install_accessors => sub { }; 1; + +__END__ + +=pod + +=head1 NAME + +MooseX::AttributeHelpers::Composite:Trait + +=head1 SYNOPSIS + + package Foo; + use Moose; + use MooseX::AttributeHelpers; + + has foo => ( + #metaclass => 'Composite', + traits => ['MooseX::AttributeHelpers::Composite::Trait'], + is => 'ro', + isa => 'Int', + default => 0, + provides => { + Counter => { + inc => 'inc_foo', + reset => 'reset_foo', + }, + Number => { + mul => 'mul_foo', + }, + # My::Method::Provider => { + # some_method => 'foo_method', + #}, + }, + ); + + package main; + + my $foo = Foo->new; + $foo->inc_foo; + $foo->mul_foo(3); + print $foo->foo . "\n"; + # 3 + +=head1 DESCRIPTION + +This is an expansion on the basic L idea, allowing you +to compose the methods provided by the various +L without naming +conflicts. In addition, this module provides a way to get these helper +methods without being locked into a particular +L, as it is simply a role with +a provides attribute and a method modifier. It cannot, however, be used with +old-style AttributeHelpers - the 'provides' name will conflict. + +=head1 ATTRIBUTES + +=over 4 + +=item provides + +The map that tells Composite which methods from which providers you would like +installed under which names. It follows the format + + ProviderName => { + provided_method => desired_method_name, + ... + }, + AnotherProvider => { + ... + }, + ... + +=back + +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. If you find a bug please either email me, or add the bug +to cpan-RT. + +=head1 AUTHOR + +Paul Driver Efrodwith@cpan.orgE + +=cut diff --git a/lib/MooseX/AttributeHelpers/MethodProvider.pm b/lib/MooseX/AttributeHelpers/MethodProvider.pm index 8317f29..9022690 100644 --- a/lib/MooseX/AttributeHelpers/MethodProvider.pm +++ b/lib/MooseX/AttributeHelpers/MethodProvider.pm @@ -72,3 +72,123 @@ sub add_method_provider ($;%) { } 1; + +__END__ + +=pod + +=head1 NAME + +MooseX::AttributeHelpers::MethodProvider + +=head1 SYNOPSIS + + package MooseX::AttributeHelpers::MethodProvider::Counter; + use MooseX::AttributeHelpers::MethodProvider; + + add_method_provider 'Counter' => ( + type => 'Int', + provides => { + reset => sub { + my ($attr, $reader, $writer) = @_; + return sub { $writer->($_[0], $attr->default($_[0])) }; + }, + + inc => sub { + my ($attr, $reader, $writer) = @_; + return sub { $writer->($_[0], $reader->($_[0]) + 1) }; + }, + + dec => sub { + my ($attr, $reader, $writer) = @_; + return sub { $writer->($_[0], $reader->($_[0]) - 1) }; + }, + }, + ); + + 1; + +=head1 DESCRIPTION + +MethodProvider is the interface for new functionality to be added to +L. The provided metaclasses get their method +factories from the repository defined by this package. Composite's methods +are also drawn from here. The package by itself provides no methods, but +rather functions for creating new entries in the repository - clients are +encouraged to define new method providers in individual modules (such as +L) and L +them as desired. + +=head1 METHOD SPECIFICATIONS + +In add_method_provider as well as get_provider_methods, you can specify a set +of providers to extract. This can be one of the following: + +=over 4 + +=item ':all' + +Causes all methods to be extracted. + +=item ArrayRef + +Causes the methods named in the ArrayRef to be extracted. + +=item HashRef + +Causes the methods named by the keys of the hashref to be extracted with the +names specified by their corresponding value, e.g. C<{inc => 'my_inc'}> + +=back + +=head1 EXPORTED FUNCTIONS + +=over 4 + +=item add_method_provider + +This is how to define a new method provider. It takes one positional argument +(the name of the MethodProvider) and three keyword arguments: + +=over 4 + +=item type + +A Moose type (such as Maybe[Str]). Validation will be done when applying to +an attribute to make sure it is this type or a subtype. + +=item consumes + +A hashref of other method providers (which must be defined, so +L the modules that define them first), of the form +C<{ProviderName => Specification}>. + +=item provides + +A hashref of method names to provide to subrefs. The subs take three +arguments (an attribute, the attribute's reader, and the attribute's writer) +and return a new sub that does some action to the attribute. + +=back + +=item get_provider_methods I + +Returns the methods for $provider_name as indicated by $specification. + +=item get_provider_type + +Returns the type of a method provider. + +=back + +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. If you find a bug please either email me, or add the bug +to cpan-RT. + +=head1 AUTHOR + +Paul Driver Efrodwith@cpan.orgE + +=cut diff --git a/lib/MooseX/AttributeHelpers/MethodProvider/Number.pm b/lib/MooseX/AttributeHelpers/MethodProvider/Number.pm index 2a959ee..c9be4aa 100644 --- a/lib/MooseX/AttributeHelpers/MethodProvider/Number.pm +++ b/lib/MooseX/AttributeHelpers/MethodProvider/Number.pm @@ -75,7 +75,7 @@ to cpan-RT. =head1 AUTHOR -Paul Driver Efrowith@cpan.orgE +Paul Driver Efrodwith@cpan.orgE =head1 COPYRIGHT AND LICENSE