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<MooseX::Role::Parameterized::Tutorial>
+
+B<Stop!> If you're new here, please read
+L<MooseX::Role::Parameterized::Tutorial>.
+
+=head1 DESCRIPTION
+
+Your parameterized role consists of two things: parameter declarations and a
+C<role> block.
+
+Parameters are declared using the L</parameter> keyword which very much
+resembles L<Moose/has>. You can use any option that L<Moose/has> accepts.
+These parameters will get their values when the consuming class (or role) uses
+L<Moose/with>. A parameter object will be constructed with these values, and
+passed to the C<role> block.
+
+The C<role> block then uses the usual L<Moose::Role> 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<method NAME => sub { ... };>. This is due to a limitation in Perl. In return
+though you can use parameters I<in your methods>!
+
+L<Moose::Role/alias> and L<Moose::Role/excludes> 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<alias> or C<excludes> is an error.
+
+=head1 AUTHOR
+
+Shawn M Moore, C<< <sartak@bestpractical.com> >>
+
+=cut
+
MooseX::Role::Parameterized::Tutorial - why and how
-=head1 ROLES
+=head1 MOTIVATION
-Roles are composable units of behavior. See L<Moose::Cookbook::Roles::Recipe1>
-for an introduction to L<Moose::Role>.
+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<Moose::Cookbook::Roles::Recipe1> for an introduction to L<Moose::Role>.
-=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<alias>
+for renaming methods to avoid conflicts, and C<excludes> for ignoring methods
+you don't want or need (see L<Moose::Cookbook::Roles::Recipe2> for more
+about C<alias> and C<excludes>).
-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<alias> for renaming methods to avoid conflicts, and
-C<excludes> for ignoring methods you don't want or need (see
-L<Moose::Cookbook::Roles::Recipe2> for more about C<alias> and C<excludes>).
+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<alias> and C<excludes> 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<with>
+The syntax of a class consuming a parameterized role has not changed from the
+standard C<with>. You pass in parameters just like you pass in C<alias> and
+C<excludes> to ordinary roles:
+
+ with 'MyRole::InstrumentMethod' => {
+ method_name => 'dbh_do',
+ log_to => 'query.log',
+ };
+
=head3 C<parameter>
+Inside your parameterized role, you specify a set of parameters. This is
+exactly like specifying the attributes of a class. Instead of C<has> you use
+the keyword C<parameter>, but your parameters can use any options to C<has>.
+
+ parameter 'delegation' => (
+ is => 'ro',
+ isa => 'HashRef|ArrayRef|RegexpRef',
+ predicate => 'has_delegation',
+ );
+
+Behind the scenes, C<parameter> uses C<has> to add attributes to a parameter
+class. The arguments to C<with> are used to construct a parameter object, which
+has the attributes specified by calls to C<parameter>. The parameter object is
+then passed to...
+
=head3 C<role>
+C<role> 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<has>,
+method modifiers, and so on. You receive as an argument the parameter object
+constructed by C<with>. 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<method name => sub { ... }> instead of the usual C<sub name { ... }>. 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
projects / gitmo/MooseX-Role-Parameterized.git / commitdiff