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 It's easy to extend and change Moose, and this is part of what makes
  10 Moose so powerful. You can use the MOP 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 this with the
  15 L<Moose::Manual::MOP> docs. There are also several extension recipes
  16 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 L<MooseX::AttributeHelpers>
  25
  26 If you only look at one extension, it should be this one. It provides
  27 the equivalent of delegation for all of Perl's native data types, such
  28 as array reference, hash references, numbers, strings, etc.
  29
  30 This lets you create I<much> cleaner and fluent APIs.
  31
  32   package User;
  33
  34   use Moose;
  35   use MooseX::AttributeHelpers;
  36
  37   has '_orders' => (
  38       metaclass => 'Collection::Array',
  39       is        => 'ro',
  40       isa       => 'ArrayRef',
  41       default   => sub { [] },
  42       provides  => {
  43           push     => 'add_order',
  44           shift    => 'next_order',
  45           elements => 'orders',
  46       },
  47   );
  48
  49 Instead of directly exposing an array reference, we have three
  50 well-named, easy to use methods.
  51
  52 =head1 L<Moose::Autobox>
  53
  54 MooseX::AttributeHelpers, but turned inside out, Moose::Autobox provides
  55 methods on both arrays/hashes/etc. but also references to them, using
  56 Moose roles, allowing you do to things like:
  57
  58   use Moose::Autobox;
  59
  60   $somebody_elses_object->orders->push($order);
  61
  62 Lexically scoped and not to everybody's taste, but very handy for sugaring
  63 up other people's APIs and your own code.
  64
  65 =head1 L<MooseX::StrictConstructor>
  66
  67 By default, Moose lets you pass any old junk into a class's
  68 constructor. If you load L<MooseX::StrictConstructor>, your class will
  69 throw an error if it sees something it doesn't recognize;
  70
  71   package User;
  72
  73   use Moose;
  74   use MooseX::StrictConstructor;
  75
  76   has 'name';
  77   has 'email';
  78
  79   User->new( name => 'Bob', emali => 'bob@example.com' );
  80
  81 With L<MooseX::StrictConstructor>, that typo ("emali") will cause a
  82 runtime error. With plain old Moose, the "emali" attribute would be
  83 silently ignored.
  84
  85 =head1 L<MooseX::Params::Validate>
  86
  87 We have high hopes for the future of L<MooseX::Method::Signatures> and
  88 L<MooseX::Declare>. However, these modules, while used regularly in
  89 production by some of the more insane members of the community, are
  90 still marked alpha just in case backwards incompatible changes need to
  91 be made.
  92
  93 If you don't want to risk that, for now we recommend the decidedly more
  94 clunky (but also faster and simpler) L<MooseX::Params::Validate>. This
  95 module lets you apply Moose types and coercions to any method
  96 arguments.
  97
  98   package User;
  99
 100   use Moose;
 101   use MooseX::Params::Validate;
 102
 103   sub login {
 104       my $self = shift;
 105       my ($password)
 106           = validated_list( \@_, password => { isa => 'Str', required => 1 } );
 107
 108       ...
 109   }
 110
 111 =head1 L<MooseX::Getopt>
 112
 113 This is a role which adds a C<new_with_options> method to your
 114 class. This is a constructor that takes the command line options and
 115 uses them to populate attributes.
 116
 117 This makes writing a command-line application as a module trivially
 118 simple:
 119
 120   package App::Foo;
 121
 122   use Moose;
 123   with 'MooseX::Getopt';
 124
 125   has 'input' => (
 126       is       => 'ro',
 127       isa      => 'Str',
 128       required => 1
 129   );
 130
 131   has 'output' => (
 132       is       => 'ro',
 133       isa      => 'Str',
 134       required => 1
 135   );
 136
 137   sub run { ... }
 138
 139 Then in the script that gets run we have:
 140
 141   use App::Foo;
 142
 143   App::Foo->new_with_options->run;
 144
 145 From the command line, someone can execute the script:
 146
 147   foo@example> foo --input /path/to/input --output /path/to/output
 148
 149 =head1 L<MooseX::Singleton>
 150
 151 To be honest, using a singleton is just a way to have a magic global
 152 variable in languages that don't actually have global variables.
 153
 154 In perl, you can just as easily use a global. However, if your
 155 colleagues are Java-infected, they might prefer a singleton. Also, if
 156 you have an existing class that I<isn't> a singleton but should be,
 157 using L<MooseX::Singleton> is the easiest way to convert it.
 158
 159   package Config;
 160
 161   use MooseX::Singleton; # instead of Moose
 162
 163   has 'cache_dir' => ( ... );
 164
 165 It's that simple.
 166
 167 =head1 EXTENSIONS TO CONSIDER
 168
 169 There are literally dozens of other extensions on CPAN. This is a list
 170 of extensions that you might find useful, but we're not quite ready to
 171 endorse just yet.
 172
 173 =head2 L<MooseX::Declare>
 174
 175 Extends Perl with Moose-based keywords using C<Devel::Declare>. Very
 176 cool, but still new and experimental.
 177
 178   class User {
 179
 180       has 'name'  => ( ... );
 181       has 'email' => ( ... );
 182
 183       method login (Str $password) { ... }
 184   }
 185
 186 =head2 L<MooseX::Types>
 187
 188 This extension helps you build a type library for your application. It
 189 also lets you predeclare type names and use them as barewords.
 190
 191   use MooseX::Types -declare => ['PositiveInt'];
 192   use MooseX::Types::Moose 'Int';
 193
 194   subtype PositiveInt
 195       => as Int,
 196       => where { $_ > 0 }
 197       => message {"Int is not larger than 0"};
 198
 199 One nice feature is that those bareword names are actually namespaced
 200 in Moose's type registry, so multiple applications can use the same
 201 bareword names, even if the type definitions differ.
 202
 203 =head2 L<MooseX::Types::Structured>
 204
 205 This extension builds on top of L<MooseX::Types> to let you declare
 206 complex data structure types.
 207
 208   use MooseX::Types -declare => [ qw( Name Color ) ];
 209   use MooseX::Types::Moose qw(Str Int);
 210   use MooseX::Types::Structured qw(Dict Tuple Optional);
 211
 212   subtype Name
 213       => as Dict[ first => Str, middle => Optional[Str], last => Str ];
 214
 215   subtype Color
 216       => as Tuple[ Int, Int, Int, Optional[Int] ];
 217
 218 Of course, you could always use objects to represent these sorts of
 219 things too.
 220
 221 =head2 L<MooseX::ClassAttribute>
 222
 223 This extension provides class attributes for Moose classes. The
 224 declared class attributes are introspectable just like regular Moose
 225 attributes.
 226
 227   package User;
 228
 229   use Moose;
 230   use MooseX::ClassAttribute;
 231
 232   has 'name' => ( ... );
 233
 234   class_has 'Cache' => ( ... );
 235
 236 Note however that this class attribute does I<not> inherit like a
 237 L<Class::Data::Inheritable> or similar attribute - calling
 238
 239   $subclass->Cache($cache);
 240
 241 will set it for the superclass as well. Additionally, class data is usually
 242 The Wrong Thing To Do in a strongly OO program since it makes testing a
 243 lot harder - consider carefully whether you'd be better off with an object
 244 that's passed around instead.
 245
 246 =head2 L<MooseX::Daemonize>
 247
 248 This is a role that provides a number of methods useful for creating a
 249 daemon, including methods for starting and stopping, managing a PID
 250 file, and signal handling.
 251
 252 =head2 L<MooseX::Role::Parameterized>
 253
 254 If you find yourself wanting a role that customizes itself for each
 255 consumer, this is the tool for you. With this module, you can create a
 256 role that accepts parameters and generates attributes, methods, etc. on
 257 a customized basis for each consumer.
 258
 259 =head2 L<MooseX::POE>
 260
 261 This is a small wrapper that ties together a Moose class with
 262 C<POE::Session>, and gives you an C<event> sugar function to declare
 263 event handlers.
 264
 265 =head2 L<MooseX::FollowPBP>
 266
 267 Automatically names all accessors I<Perl Best Practices>-style,
 268 "get_size" and "set_size".
 269
 270 =head2 L<MooseX::SemiAffordanceAccessor>
 271
 272 Automatically names all accessors with an explicit set and implicit
 273 get, "size" and "set_size".
 274
 275 =head2 L<MooseX::NonMoose>
 276
 277 MooseX::NonMoose allows for easily subclassing non-Moose classes with Moose,
 278 taking care of the annoying details connected with doing this, such as
 279 setting up proper inheritance from Moose::Object and installing
 280 (and inlining, at make_immutable time) a constructor that makes sure things
 281 like BUILD methods are called.
 282
 283 =head1 AUTHOR
 284
 285 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 286
 287 =head1 COPYRIGHT AND LICENSE
 288
 289 Copyright 2009 by Infinity Interactive, Inc.
 290
 291 L<http://www.iinteractive.com>
 292
 293 This library is free software; you can redistribute it and/or modify
 294 it under the same terms as Perl itself.
 295
 296 =cut