lib/Moose/Manual/MooseX.pod

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