From: Shawn M Moore Date: Tue, 2 Dec 2008 08:40:45 +0000 (+0000) Subject: More docs X-Git-Tag: 0.05~59 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=gitmo%2FMooseX-Role-Parameterized.git;a=commitdiff_plain;h=a4ac31faae1285a2845e8df887f1543b12970604 More docs --- diff --git a/lib/MooseX/Role/Parameterized.pm b/lib/MooseX/Role/Parameterized.pm index 2879984..7080b66 100644 --- a/lib/MooseX/Role/Parameterized.pm +++ b/lib/MooseX/Role/Parameterized.pm @@ -172,3 +172,89 @@ sub augment { croak "Roles cannot support 'augment'" } 1; +__END__ + +=head1 NAME + +MooseX::Role::Parameterized - parameterized roles, at long last + +=head1 SYNOPSIS + + package MyRole::Counter; + use MooseX::Role::Parameterized; + + parameter name => ( + is => 'ro', + isa => 'Str', + required => 1, + ); + + role { + my $p = shift; + + my $name = $p->name; + + has $name => ( + is => 'rw', + isa => 'Int', + default => 0, + ); + + method "increment_$name" => sub { + my $self = shift; + $self->$name($self->$name + 1); + }; + + method "decrement_$name" => sub { + my $self = shift; + $self->$name($self->$name - 1); + }; + }; + + package MyGame::Tile; + use Moose; + + with 'MyRole::Counter' => { name => 'stepped_on' }; + +=head1 L + +B If you're new here, please read +L. + +=head1 DESCRIPTION + +Your parameterized role consists of two things: parameter declarations and a +C block. + +Parameters are declared using the L keyword which very much +resembles L. You can use any option that L accepts. +These parameters will get their values when the consuming class (or role) uses +L. A parameter object will be constructed with these values, and +passed to the C block. + +The C block then uses the usual L keywords to build up a +role. You can shift off the parameter object to inspect what the consuming +class provided as parameters. You can use the parameters to make your role +customizable! + +There are many paths to parameterized roles (hopefully with a consistent enough +API); I believe this to be the easiest and most flexible implementation. +Coincidentally, Pugs has a very similar design (I'm not convinced that that is +a good thing yet). + +=head1 CAVEATS + +You must use this syntax to declare methods in the role block: +C sub { ... };>. This is due to a limitation in Perl. In return +though you can use parameters I! + +L and L are not yet supported. Because +I'm totally unsure of whether they should be handled by this module, both +declaring and providing a parameter named C or C is an error. + +=head1 AUTHOR + +Shawn M Moore, C<< >> + +=cut + diff --git a/lib/MooseX/Role/Parameterized/Tutorial.pm b/lib/MooseX/Role/Parameterized/Tutorial.pm index ab67341..af18902 100644 --- a/lib/MooseX/Role/Parameterized/Tutorial.pm +++ b/lib/MooseX/Role/Parameterized/Tutorial.pm @@ -7,28 +7,73 @@ __END__ MooseX::Role::Parameterized::Tutorial - why and how -=head1 ROLES +=head1 MOTIVATION -Roles are composable units of behavior. See L -for an introduction to L. +Roles are composable units of behavior. They are useful for factoring out +functionality common to many classes from any part of your class hierarchy.See +L for an introduction to L. -=head1 MOTIVATION +While combining roles affords you a great deal of flexibility, individual roles +have very little in the way of configurability. Core Moose provides C +for renaming methods to avoid conflicts, and C for ignoring methods +you don't want or need (see L for more +about C and C). -Roles are exceedingly useful. While combining roles affords you a great deal of -flexibility, individual roles have very little in the way of configurability. -Core Moose provides C for renaming methods to avoid conflicts, and -C for ignoring methods you don't want or need (see -L for more about C and C). +Because roles serve many different masters, they usually provide only the least +common denominator of functionality. Not all consumers of a role have a C<>. +Thus, more configurability than C and C is required. Perhaps +your role needs to know which method to call when it is done. Or what default +value to use for its url attribute. +Parameterized roles offer exactly this solution. =head1 USAGE =head3 C +The syntax of a class consuming a parameterized role has not changed from the +standard C. You pass in parameters just like you pass in C and +C to ordinary roles: + + with 'MyRole::InstrumentMethod' => { + method_name => 'dbh_do', + log_to => 'query.log', + }; + =head3 C +Inside your parameterized role, you specify a set of parameters. This is +exactly like specifying the attributes of a class. Instead of C you use +the keyword C, but your parameters can use any options to C. + + parameter 'delegation' => ( + is => 'ro', + isa => 'HashRef|ArrayRef|RegexpRef', + predicate => 'has_delegation', + ); + +Behind the scenes, C uses C to add attributes to a parameter +class. The arguments to C are used to construct a parameter object, which +has the attributes specified by calls to C. The parameter object is +then passed to... + =head3 C +C takes a block of code that will be used to generate your role with its +parameters bound. Here is where you put your regular role code: use C, +method modifiers, and so on. You receive as an argument the parameter object +constructed by C. You can access the parameters just like regular +attributes on that object (assuming you declared them readable). + +Each time you compose this parameterized role, the role {} block will be +executed. It will receive a new parameter object and produce an entirely new +role. + +Due to limitations inherent in Perl, you must declare methods with +C sub { ... }> instead of the usual C. Your +methods may, of course, close over the parameter object. This means that your +methods may use parameters however they wish! + =head1 IMPLEMENTATION NOTES =head1 USES