lib/Moose/Manual/MooseX.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::MooseX - Recommended Moose Extensions
   6
   7 =head1 MooseX?
   8
   9 One of the great things about Moose is that it is easy to extend and
  10 override. You can use the meta-model API to do things your own way,
  11 add new features, and generally customize your Moose.
  12
  13 Writing your own extensions does require a good understanding of the
  14 meta-model. You can start learning about thiswith the
  15 L<Moose::Manual::Introspection> docs. There are also several extensions
  16 recipes in the L<Moose::Cookbook>.
  17
  18 Explaining how to write extensions is beyond the scope of this
  19 manual. Fortunately, lots of people have already written extensions
  20 and put them on CPAN for you.
  21
  22 This document covers a few of the ones we like best.
  23
  24 =head1 MooseX::AttributeHelpers
  25
  26 If you only look at one extension, it should be this one. The name
  27 isn't the best, but what it does it provide the equivalent of
  28 delegation for all of Perl's native data types, such as array
  29 reference, hash references, numbers, strings, etc.
  30
  31 This lets you create I<much> cleaner and fluent APIs.
  32
  33   package User;
  34
  35   use Moose;
  36   use MooseX::AttributeHelpers;
  37
  38   has '_orders' => (
  39       metaclass => 'Collection::Array',
  40       is        => 'ro',
  41       isa       => 'ArrayRef',
  42       default   => sub { [] },
  43       provides  => {
  44           push     => 'add_order',
  45           shift    => 'next_order',
  46           elements => 'orders',
  47       },
  48   );
  49
  50 Instead of directly exposing an array reference, we have three
  51 well-named, easy to use methods.
  52
  53 =head1 MooseX::StrictConstructor
  54
  55 By default, Moose lets you pass any old junk into a class's
  56 constructor. If you load C<MooseX::StrictConstructor>, your class will
  57 throw an error if it sees something it doesn't recognize;
  58
  59   package User;
  60
  61   use Moose;
  62   use MooseX::StrictConstructor;
  63
  64   has 'name';
  65   has 'email';
  66
  67   User->new( name => 'Bob', emali => 'bob@example.com' );
  68
  69 With C<MooseX::StrictConstructor>, that typo ("emali") will cause a
  70 runtime error. Otherwise, the "emali" attribute would just be silently
  71 ignored.
  72
  73 =head1 MooseX::Params::Validate
  74
  75 We have high hopes for the future of C<MooseX::Method::Signatures> and
  76 C<MooseX::Declare>. However, for now we recommend the decidely more
  77 clunky (but also faster and simpler) C<MooseX::Params::Validate>. This
  78 module lets you apply Moose types and coercions to any method
  79 arguments.
  80
  81   package User;
  82
  83   use Moose;
  84   use MooseX::Params::Validate qw( validatep );
  85
  86   sub login {
  87       my $self = shift;
  88       my ($password)
  89           = validatep( \@_, password => { isa => 'Str', required => 1 } );
  90
  91       ...
  92   }
  93
  94 =head1 MooseX::Getopt
  95
  96 This is a role which adds a C<new_with_options> method to your
  97 class. This is a constructor that takes the command line options and
  98 uses them to populate attributes.
  99
 100 Thia makes writing a command-line application as a module trivially
 101 simple:
 102
 103   package App::Foo;
 104
 105   use Moose;
 106   with 'MooseX::Getopt';
 107
 108   has 'input' => (
 109       is       => 'ro',
 110       isa      => 'Str',
 111       required => 1
 112   );
 113
 114   has 'output' => (
 115       is       => 'ro',
 116       isa      => 'Str',
 117       required => 1
 118   );
 119
 120   sub run { ... }
 121
 122 Then in the script that gets run we have:
 123
 124   use App::Foo;
 125
 126   App::Foo->new_with_options->run;
 127
 128 =head1 MooseX::Singleton
 129
 130 To be honest, using a singleton is often a hack, but it sure is a
 131 handy hack. C<MooseX::Singleton> lets you have a Moose class that's a
 132 singleton:
 133
 134   package Config;
 135
 136   use MooseX::Singleton; # instead of Moose
 137
 138   has 'cache_dir' => ( ... );
 139
 140 It's that simple.
 141
 142 =head1 MooseX::MetaDescription
 143
 144 This module lets you attach an arbitrary hash reference of metadata to
 145 an attribute.
 146
 147   has 'image_name' => (
 148       metaclass   => 'MooseX::MetaDescription::Meta::Attribute',
 149       is          => 'ro',
 150       isa         => 'Str',
 151       description => {
 152           html_display => 'Image',
 153       }
 154   );
 155
 156 =head1 EXTENSIONS TO CONSIDER
 157
 158 There are literally dozens of other extensions on CPAN. These are a
 159 few to consider. We're not quite ready to recommend them outright,
 160 though. There's a couple reasons for this. One, they may be very
 161 specialized. Two, they may be immature. Three, they may not be quite
 162 right yet. Four, we may not all agree they're such a great idea.
 163
 164 =head2 MooseX::Declare
 165
 166 Extends Perl with Moose-based keywords using C<Devel::Declare>. Very
 167 cool, but still new and experimental.
 168
 169   class User {
 170
 171       has 'name'  => ( ... );
 172       has 'email' => ( ... );
 173
 174       method login (Str $password) { ... }
 175   }
 176
 177 =head2 MooseX::Types
 178
 179 This extension helps you build a type library for your application. It
 180 also lets you pre-declare type names and use them as barewords.
 181
 182   use MooseX::Types -declare => ['PosInt'];
 183   use MooseX::Types::Moose 'Int';
 184
 185   subtype PositiveInt
 186       => as Int,
 187       => where { $_ > 0 }
 188       => message {"Int is not larger than 0"};
 189
 190 One nice feature is the those bareword names are actually namespaces
 191 in Moose's type registry, so multiple applications can use the same
 192 bareword names, even if the type definitions differ.
 193
 194 =head2 MooseX::Types::Structured
 195
 196 This extension builds on top of C<MooseX::Types> to let you declare
 197 complex data structure types.
 198
 199   use MooseX::Types -declare => [ qw( Name Color ) ];
 200   use MooseX::Types::Moose qw(Str Int);
 201   use MooseX::Types::Structured qw(Dict Tuple Optional);
 202
 203   subtype Name
 204       => as Dict[ first => Str, middle => Optional[Str], last => Str ];
 205
 206   subtype Color
 207       => as Tuple[ Int, Int, Int, Optional[Int] ];
 208
 209 Of course, you could always use objects to represent these sorts of
 210 things too.
 211
 212 =head2 MooseX::ClassAttribute
 213
 214 This extension provides class attributes for Moose classes. The
 215 declared class attributes are introspectable just like regular Moose
 216 attributes.
 217
 218   package User;
 219
 220   use Moose;
 221   use MooseX::ClassAttribute;
 222
 223   has 'name' => ( ... );
 224
 225   class_has 'Cache' => ( ... );
 226
 227 =head2 MooseX::Daemonize
 228
 229 This is a role that provides a number of methods useful for creating a
 230 daemon, including methods for starting and stopping, managing a PID
 231 file, and signal handling.
 232
 233 =head2 MooseX::Role::Parameterized
 234
 235 If you find yourself wanting a role that customizes itself for each
 236 consumer, this is the tool for you. With this module, you can create a
 237 role that accepts parameters and generates attributes, methods, etc on
 238 a customized basis for each consumer.
 239
 240 =head2 MooseX::POE
 241
 242 This is a small wrapper that ties together a Moose class with
 243 C<POE::Session>, and gives you an C<event> sugar function to declare
 244 event handlers.
 245
 246 =head2 MooseX::FollowPBP
 247
 248 Automatically names all accessors I<Perl Best Practices>-style,
 249 "get_name" and "set_name".
 250
 251 =head2 MooseX::SemiAffordanceAccessor
 252
 253 Autoamtically names all accessors with an explicit set and implicit
 254 get, "name" and "set_name".
 255
 256 =head1 AUTHOR
 257
 258 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 259
 260 =head1 COPYRIGHT AND LICENSE
 261
 262 Copyright 2008 by Infinity Interactive, Inc.
 263
 264 L<http://www.iinteractive.com>
 265
 266 This library is free software; you can redistribute it and/or modify
 267 it under the same terms as Perl itself.
 268
 269 =cut