lib/MooseX/Role/Parameterized/Tutorial.pod

   1 package MooseX::Role::Parameterized::Tutorial;
   2 confess "Don't use this module, read it!";
   3
   4 __END__
   5
   6 =head1 NAME
   7
   8 MooseX::Role::Parameterized::Tutorial - why and how
   9
  10 =head1 MOTIVATION
  11
  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>.
  15
  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>).
  21
  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.
  27
  28 Parameterized roles offer exactly this solution.
  29
  30 =head1 USAGE
  31
  32 =head3 C<with>
  33
  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:
  37
  38     with 'MyRole::InstrumentMethod' => {
  39         method_name => 'dbh_do',
  40         log_to      => 'query.log',
  41     };
  42
  43 =head3 C<parameter>
  44
  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>.
  48
  49     parameter 'delegation' => (
  50         isa       => 'HashRef|ArrayRef|RegexpRef',
  51         predicate => 'has_delegation',
  52     );
  53
  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...
  58
  59 =head3 C<role>
  60
  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).
  66
  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
  69 role.
  70
  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!
  75
  76 =head1 IMPLEMENTATION NOTES
  77
  78 =head1 USES
  79
  80 Ideally these will become fully-explained examples in something resembling
  81 L<Moose::Cookbook>. But for now, only a braindump.
  82
  83 =over 4
  84
  85 =item Configure a role's attributes
  86
  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.
  89
  90     parameter traits => (
  91         isa     => 'ArrayRef[Str]',
  92         default => sub { [] },
  93     );
  94
  95     has action => (
  96         traits => $p->traits,
  97         ...
  98     );
  99
 100 =item Inform a role of your class' attributes and methods
 101
 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.
 105
 106     parameter instrument_method => (
 107         isa      => 'Str',
 108         required => 1,
 109     );
 110
 111     around $p->instrument_method => sub { ... };
 112
 113 =item Arbitrary execution choices
 114
 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
 117 states.
 118
 119     parameter save_intermediate => (
 120         isa     => 'Bool',
 121         default => 0,
 122     );
 123
 124     method process => sub {
 125         ...
 126         if ($p->save_intermediate) { ... }
 127         ...
 128     };
 129
 130 =item Deciding a backend
 131
 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.
 134
 135     parameter format => (
 136         isa     => (enum ['Storable', 'YAML', 'JSON']),
 137         default => 'Storable',
 138     );
 139
 140     if ($p->format eq 'Storable') {
 141         method freeze => sub { ... };
 142         method thaw   => sub { ... };
 143     }
 144     elsif ($p->format eq 'YAML') ...
 145     ...
 146
 147 =back
 148
 149 =cut
 150