1 package Moose::Manual::MooseX;
3 # ABSTRACT: Recommended Moose extensions
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.
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>.
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.
24 This document covers a few of the ones we like best.
26 =head1 L<MooseX::AttributeHelpers>
28 The functionality of this MooseX module has been moved into Moose core.
29 See L<Moose::Meta::Attribute::Native>.
31 =head1 L<Moose::Autobox>
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:
39 $somebody_elses_object->orders->push($order);
41 Lexically scoped and not to everybody's taste, but very handy for sugaring
42 up other people's APIs and your own code.
44 =head1 L<MooseX::StrictConstructor>
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;
53 use MooseX::StrictConstructor;
58 User->new( name => 'Bob', emali => 'bob@example.com' );
60 With L<MooseX::StrictConstructor>, that typo ("emali") will cause a
61 runtime error. With plain old Moose, the "emali" attribute would be
64 =head1 L<MooseX::Params::Validate>
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
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
80 use MooseX::Params::Validate;
85 = validated_list( \@_, password => { isa => 'Str', required => 1 } );
90 =head1 L<MooseX::Getopt>
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.
96 This makes writing a command-line application as a module trivially
102 with 'MooseX::Getopt';
118 Then in the script that gets run we have:
122 App::Foo->new_with_options->run;
124 From the command line, someone can execute the script:
126 foo@example> foo --input /path/to/input --output /path/to/output
128 =head1 L<MooseX::Singleton>
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.
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.
140 use MooseX::Singleton; # instead of Moose
142 has 'cache_dir' => ( ... );
146 =head1 EXTENSIONS TO CONSIDER
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
152 =head2 L<MooseX::Declare>
154 Extends Perl with Moose-based keywords using C<Devel::Declare>. Very
155 cool, but still new and experimental.
159 has 'name' => ( ... );
160 has 'email' => ( ... );
162 method login (Str $password) { ... }
165 =head2 L<MooseX::Types>
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.
170 use MooseX::Types -declare => ['PositiveInt'];
171 use MooseX::Types::Moose 'Int';
176 message { "Int is not larger than 0" };
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.
182 =head2 L<MooseX::Types::Structured>
184 This extension builds on top of L<MooseX::Types> to let you declare
185 complex data structure types.
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);
192 => as Dict[ first => Str, middle => Optional[Str], last => Str ];
195 => as Tuple[ Int, Int, Int, Optional[Int] ];
197 Of course, you could always use objects to represent these sorts of
200 =head2 L<MooseX::ClassAttribute>
202 This extension provides class attributes for Moose classes. The
203 declared class attributes are introspectable just like regular Moose
209 use MooseX::ClassAttribute;
211 has 'name' => ( ... );
213 class_has 'Cache' => ( ... );
215 Note however that this class attribute does I<not> inherit like a
216 L<Class::Data::Inheritable> or similar attribute - calling
218 $subclass->Cache($cache);
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.
225 =head2 L<MooseX::Daemonize>
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.
231 =head2 L<MooseX::Role::Parameterized>
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.
238 =head2 L<MooseX::POE>
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
244 =head2 L<MooseX::FollowPBP>
246 Automatically names all accessors I<Perl Best Practices>-style,
247 "get_size" and "set_size".
249 =head2 L<MooseX::SemiAffordanceAccessor>
251 Automatically names all accessors with an explicit set and implicit
252 get, "size" and "set_size".
254 =head2 L<MooseX::NonMoose>
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.