1 package MooseX::Role::Parameterized::Tutorial;
2 confess "Don't use this module, read it!";
8 MooseX::Role::Parameterized::Tutorial - why and how
12 Roles are composable units of behavior. They are useful for factoring out
13 functionality common to many classes from any part of your class hierarchy.See
14 L<Moose::Cookbook::Roles::Recipe1> for an introduction to L<Moose::Role>.
16 While combining roles affords you a great deal of flexibility, individual roles
17 have very little in the way of configurability. Core Moose provides C<alias>
18 for renaming methods to avoid conflicts, and C<excludes> for ignoring methods
19 you don't want or need (see L<Moose::Cookbook::Roles::Recipe2> for more
20 about C<alias> and C<excludes>).
22 Because roles serve many different masters, they usually provide only the least
23 common denominator of functionality. To empower roles further, more
24 configurability than C<alias> and C<excludes> is required. Perhaps your role
25 needs to know which method to call when it is done. Or what default value to
26 use for its url attribute.
28 Parameterized roles offer exactly this solution.
34 The syntax of a class consuming a parameterized role has not changed from the
35 standard C<with>. You pass in parameters just like you pass in C<alias> and
36 C<excludes> to ordinary roles:
38 with 'MyRole::InstrumentMethod' => {
39 method_name => 'dbh_do',
40 log_to => 'query.log',
45 Inside your parameterized role, you specify a set of parameters. This is
46 exactly like specifying the attributes of a class. Instead of C<has> you use
47 the keyword C<parameter>, but your parameters can use any options to C<has>.
49 parameter 'delegation' => (
50 isa => 'HashRef|ArrayRef|RegexpRef',
51 predicate => 'has_delegation',
54 Behind the scenes, C<parameter> uses C<has> to add attributes to a parameter
55 class (except the "is" option defaults to "ro" for convenience). The arguments
56 to C<with> are used to construct a parameter object, which has the attributes
57 specified by calls to C<parameter>. The parameter object is then passed to...
61 C<role> takes a block of code that will be used to generate your role with its
62 parameters bound. Here is where you declare parameterized components: use
63 C<has>, method modifiers, and so on. You receive as an argument the parameter
64 object constructed by C<with>. You can access the parameters just like regular
65 attributes on that object (assuming you declared them readable).
67 Each time you compose this parameterized role, the role {} block will be
68 executed. It will receive a new parameter object and produce an entirely new
71 Due to limitations inherent in Perl, you must declare methods with
72 C<< method name => sub { ... } >> instead of the usual C<sub name { ... }>.
73 Your methods may, of course, close over the parameter object. This means that
74 your methods may use parameters however they wish!
76 =head1 IMPLEMENTATION NOTES
80 Ideally these will become fully-explained examples in something resembling
81 L<Moose::Cookbook>. But for now, only a braindump.
85 =item Configure a role's attributes
87 You can rename methods with core Moose, but now you can rename attributes. You
88 can now also choose type, default value, whether it's required, B<traits>, etc.
91 isa => 'ArrayRef[Str]',
92 default => sub { [] },
100 =item Inform a role of your class' attributes and methods
102 Core roles can require only methods with specific names. Now your roles can
103 require that you specify a method name you wish the role to instrument, or
104 which attributes to dump to a file.
106 parameter instrument_method => (
111 around $p->instrument_method => sub { ... };
113 =item Arbitrary execution choices
115 Your role may be able to provide configuration in how the role's methods
116 operate. For example, you can tell the role whether to save intermediate
119 parameter save_intermediate => (
124 method process => sub {
126 if ($p->save_intermediate) { ... }
130 =item Deciding a backend
132 Your role may be able to freeze and thaw your instances using L<YAML>, L<JSON>,
133 L<Storable>. Which backend to use can be a parameter.
135 parameter format => (
136 isa => (enum ['Storable', 'YAML', 'JSON']),
137 default => 'Storable',
140 if ($p->format eq 'Storable') {
141 method freeze => sub { ... };
142 method thaw => sub { ... };
144 elsif ($p->format eq 'YAML') ...