lib/MooseX/Role/Parameterized/Tutorial.pm

   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 ROLES
  11
  12 Roles are composable units of behavior. See L<Moose::Cookbook::Roles::Recipe1>
  13 for an introduction to L<Moose::Role>.
  14
  15 =head1 MOTIVATION
  16
  17 Roles are exceedingly useful. While combining roles affords you a great deal of
  18 flexibility, individual roles have very little in the way of configurability.
  19 Core Moose provides C<alias> for renaming methods to avoid conflicts, and
  20 C<excludes> for ignoring methods you don't want or need (see
  21 L<Moose::Cookbook::Roles::Recipe2> for more about C<alias> and C<excludes>).
  22
  23
  24 =head1 USAGE
  25
  26 =head3 C<with>
  27
  28 =head3 C<parameter>
  29
  30 =head3 C<role>
  31
  32 =head1 IMPLEMENTATION NOTES
  33
  34 =head1 USES
  35
  36 Ideally these will become fully-explained examples in something resembling
  37 L<Moose::Cookbook>. But for now, only a braindump.
  38
  39 =over 4
  40
  41 =item Configure a role's attributes
  42
  43 You can rename methods with core Moose, but now you can rename attributes. You
  44 can now also choose type, default value, whether it's required, B<traits>, etc.
  45
  46     parameter traits => (
  47         is      => 'ro',
  48         isa     => 'ArrayRef[Str]',
  49         default => sub { [] },
  50     );
  51
  52     has action => (
  53         traits => $p->traits,
  54         ...
  55     );
  56
  57 =item Inform a role of your class' attributes and methods
  58
  59 Core roles can require only methods with specific names. Now your roles can
  60 require that you specify a method name you wish the role to instrument, or
  61 which attributes to dump to a file.
  62
  63     parameter instrument_method => (
  64         is       => 'ro',
  65         isa      => 'Str',
  66         required => 1,
  67     );
  68
  69     around $p->instrument_method => sub { ... };
  70
  71 =item Arbitrary execution choices
  72
  73 Your role may be able to provide configuration in how the role's methods
  74 operate. For example, you can tell the role whether to save intermediate
  75 states.
  76
  77     parameter save_intermediate => (
  78         is      => 'ro',
  79         isa     => 'Bool',
  80         default => 0,
  81     );
  82
  83     method process => sub {
  84         ...
  85         if ($p->save_intermediate) { ... }
  86         ...
  87     };
  88
  89 =item Deciding a backend
  90
  91 Your role may be able to freeze and thaw your instances using L<YAML>, L<JSON>,
  92 L<Storable>. Which backend to use can be a parameter.
  93
  94     parameter format => (
  95         is => 'ro',
  96         isa => (enum ['Storable', 'YAML', 'JSON']),
  97         default => 'Storable',
  98     );
  99
 100     if ($p->format eq 'Storable') {
 101         method freeze => sub { ... };
 102         method thaw   => sub { ... };
 103     }
 104     elsif ($p->format eq 'YAML') ...
 105     ...
 106
 107 =back
 108
 109 =cut
 110