8 our $VERSION = '0.091002'; # 0.91.2
9 $VERSION = eval $VERSION;
11 require Moo::sification;
19 return if $MAKERS{$target}; # already exported into this package
20 _install_coderef "${target}::extends" => "Moo::extends" => sub {
21 _load_module($_) for @_;
22 # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
23 @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
24 if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
25 delete _getstash($target)->{new};
26 Moo->_constructor_maker_for($target)
27 ->register_attribute_specs(%{$old->all_attribute_specs});
30 _install_coderef "${target}::with" => "Moo::with" => sub {
32 Moo::Role->apply_roles_to_package($target, $_[0]);
34 $MAKERS{$target} = {};
35 _install_coderef "${target}::has" => "Moo::has" => sub {
36 my ($name, %spec) = @_;
37 $class->_constructor_maker_for($target)
38 ->register_attribute_specs($name, \%spec);
39 $class->_accessor_maker_for($target)
40 ->generate_method($target, $name, \%spec);
42 foreach my $type (qw(before after around)) {
43 _install_coderef "${target}::${type}" => "Moo::${type}" => sub {
44 require Class::Method::Modifiers;
45 _install_modifier($target, $type, @_);
50 @{"${target}::ISA"} = do {
51 require Moo::Object; ('Moo::Object');
52 } unless @{"${target}::ISA"};
54 if ($INC{'Moo/HandleMoose.pm'}) {
55 Moo::HandleMoose::inject_fake_metaclass_for($target);
59 sub _accessor_maker_for {
60 my ($class, $target) = @_;
61 return unless $MAKERS{$target};
62 $MAKERS{$target}{accessor} ||= do {
63 my $maker_class = do {
65 if (my $defer_target =
66 (Sub::Defer::defer_info($target->can('new'))||[])->[0]
68 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
69 $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
76 require Method::Generate::Accessor;
77 'Method::Generate::Accessor'
84 sub _constructor_maker_for {
85 my ($class, $target, $select_super) = @_;
86 return unless $MAKERS{$target};
87 $MAKERS{$target}{constructor} ||= do {
88 require Method::Generate::Constructor;
90 my ($moo_constructor, $con);
92 if ($select_super && $MAKERS{$select_super}) {
94 $con = $MAKERS{$select_super}{constructor};
96 my $t_new = $target->can('new');
98 if ($t_new == Moo::Object->can('new')) {
100 } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
101 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
103 $moo_constructor = 1;
104 $con = $MAKERS{$pkg}{constructor};
108 $moo_constructor = 1; # no other constructor, make a Moo one
111 ($con ? ref($con) : 'Method::Generate::Constructor')
114 accessor_generator => $class->_accessor_maker_for($target),
115 construction_string => (
117 ? ($con ? $con->construction_string : undef)
118 : ('$class->'.$target.'::SUPER::new(@_)')
120 subconstructor_handler => (
121 ' if ($Moo::MAKERS{$class}) {'."\n"
122 .' '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
123 .' return $class->new(@_)'.";\n"
128 ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
139 Moo - Minimalist Object Orientation (with Moose compatiblity)
150 my $amount = shift || 1;
152 $self->pounds( $self->pounds - $amount );
162 die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
168 isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
175 my $full = Cat::Food->new(
176 taste => 'DELICIOUS.',
177 brand => 'SWEET-TREATZ',
187 This module is an extremely light-weight, high-performance L<Moose> replacement.
188 It also avoids depending on any XS modules to allow simple deployments. The
189 name C<Moo> is based on the idea that it provides almost -but not quite- two
192 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility. See
193 L</INCOMPATIBILITIES> for more details.
195 =head1 WHY MOO EXISTS
197 If you want a full object system with a rich Metaprotocol, L<Moose> is
200 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
201 takes longer to load than most of my Moo based CGI scripts take to run.
203 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
204 you want "as little as possible" - which means "no metaprotocol", which is
207 By Moo 1.0 I intend to have Moo's equivalent of L<Any::Moose> built in -
208 if Moose gets loaded, any Moo class or role will act as a Moose equivalent
211 Hence - Moo exists as its name - Minimal Object Orientation - with a pledge
212 to make it smooth to upgrade to L<Moose> when you need more than minimal
215 =head1 Moo and Moose - NEW, EXPERIMENTAL
217 If L<Moo> detects L<Moose> being loaded, it will automatically register
218 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
219 to use them in L<Moose> code without it ever realising you aren't using
222 Extending a L<Moose> class or consuming a L<Moose::Role> should also work.
224 This means that there is no need for anything like L<Any::Moose> for Moo
225 code - Moo and Moose code should simply interoperate without problem.
227 However, these features are new as of 0.91.0 (0.091000) so while serviceable,
228 they are absolutely certain to not be 100% yet; please do report bugs.
230 If you need to disable the metaclass creation, add:
234 to your code before Moose is loaded, but bear in mind that this switch is
235 currently global and turns the mechanism off entirely, so don't put this
236 in library code, only in a top level script as a temporary measure while
237 you send a bug report.
239 =head1 IMPORTED METHODS
243 Foo::Bar->new( attr1 => 3 );
247 Foo::Bar->new({ attr1 => 3 });
252 my ( $class, @args ) = @_;
254 unshift @args, "attr1" if @args % 2 == 1;
261 The default implementation of this method accepts a hash or hash reference of
262 named parameters. If it receives a single argument that isn't a hash reference
265 You can override this method in your class to handle other types of options
266 passed to the constructor.
268 This method should always return a hash reference of named options.
272 Define a C<BUILD> method on your class and the constructor will automatically
273 call the C<BUILD> method from parent down to child after the object has
274 been instantiated. Typically this is used for object validation or possibly
279 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
280 a C<DESTROY> method is created on first object construction which will call
281 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
282 method from child upwards to parents.
284 Note that the C<DESTROY> method is created on first construction of an object
285 of your class in order to not add overhead to classes without C<DEMOLISH>
286 methods; this may prove slightly surprising if you try and define your own.
290 if ($foo->does('Some::Role1')) {
294 Returns true if the object composes in the passed role.
296 =head1 IMPORTED SUBROUTINES
300 extends 'Parent::Class';
302 Declares base class. Multiple superclasses can be passed for multiple
303 inheritance (but please use roles instead).
305 Calling extends more than once will REPLACE your superclasses, not add to
306 them like 'use base' would.
314 with 'Some::Role1', 'Some::Role2';
316 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
317 class. An error will be raised if these roles have conflicting methods.
325 Declares an attribute for the class.
327 The options for C<has> are as follows:
333 B<required>, may be C<ro>, C<rw>, C<lazy> or C<rwp>.
335 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
336 a getter only - by defaulting C<reader> to the name of the attribute.
338 C<rw> generates a normal getter/setter by defauting C<accessor> to the
339 name of the attribute.
341 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
342 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
343 attributes. This feature was my attempt to fix my incompetence when
344 originally designing C<lazy_build>, and is also implemented by
345 L<MooseX::AttributeShortcuts>.
347 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
348 C<_set_${attribute_name}> for attributes that are designed to be written
349 from inside of the class, but read-only from outside.
350 This feature comes from L<MooseX::AttributeShortcuts>.
354 Takes a coderef which is meant to validate the attribute. Unlike L<Moose> Moo
355 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
359 die "$_[0] is not a number!" unless looks_like_number $_[0]
362 L<Sub::Quote aware|/SUB QUOTE AWARE>
364 If you want L<MooseX::Types> style named types, look at
365 L<MooX::Types::MooseLike>.
367 To cause your C<isa> entries to be automatically mapped to named
368 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
369 of creating an anonymous type), set:
371 $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
372 require MooseX::Types::Something;
373 return MooseX::Types::Something::TypeName();
376 Note that this example is purely illustrative; anything that returns a
377 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
378 make L<Moose> happy is fine.
382 Takes a coderef which is meant to coerce the attribute. The basic idea is to
383 do something like the following:
385 coerce => quote_sub q{
386 $_[0] + 1 unless $_[0] % 2
389 Coerce does not require C<isa> to be defined, but since L<Moose> does
390 require it, the metaclass inflation for coerce-alone is a trifle insane
391 and if you attempt to subtype the result will almost certainly break.
393 L<Sub::Quote aware|/SUB QUOTE AWARE>
399 handles => 'RobotRole'
401 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
402 becomes the list of methods to handle.
404 Takes a list of methods
406 handles => [ qw( one two ) ]
416 Takes a coderef which will get called any time the attribute is set. This
417 includes the constructor. Coderef will be invoked against the object with the
418 new value as an argument.
420 If you set this to just C<1>, it generates a trigger which calls the
421 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
422 L<MooseX::AttributeShortcuts>.
424 Note that Moose also passes the old value, if any; this feature is not yet
427 L<Sub::Quote aware|/SUB QUOTE AWARE>
431 Takes a coderef which will get called with $self as its only argument
432 to populate an attribute if no value is supplied to the constructor - or
433 if the attribute is lazy, when the attribute is first retrieved if no
434 value has yet been provided.
436 Note that if your default is fired during new() there is no guarantee that
437 other attributes have been populated yet so you should not rely on their
440 L<Sub::Quote aware|/SUB QUOTE AWARE>
444 Takes a method name which will return true if an attribute has a value.
446 If you set this to just C<1>, the predicate is automatically named
447 C<has_${attr_name}> if your attribute's name does not start with an
448 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
449 This feature comes from L<MooseX::AttributeShortcuts>.
453 Takes a method name which will be called to create the attribute - functions
454 exactly like default except that instead of calling
462 If you set this to just C<1>, the predicate is automatically named
463 C<_build_${attr_name}>. This feature comes from L<MooseX::AttributeShortcuts>.
467 Takes a method name which will clear the attribute.
469 If you set this to just C<1>, the clearer is automatically named
470 C<clear_${attr_name}> if your attribute's name does not start with an
471 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
472 This feature comes from L<MooseX::AttributeShortcuts>.
476 B<Boolean>. Set this if you want values for the attribute to be grabbed
477 lazily. This is usually a good idea if you have a L</builder> which requires
478 another attribute to be set.
482 B<Boolean>. Set this if the attribute must be passed on instantiation.
486 The value of this attribute will be the name of the method to get the value of
487 the attribute. If you like Java style methods, you might set this to
492 The value of this attribute will be the name of the method to set the value of
493 the attribute. If you like Java style methods, you might set this to
498 B<Boolean>. Set this if you want the reference that the attribute contains to
499 be weakened; use this when circular references are possible, which will cause
504 Takes the name of the key to look for at instantiation time of the object. A
505 common use of this is to make an underscored attribute have a non-underscored
506 initialization name. C<undef> means that passing the value in on instantiation
513 before foo => sub { ... };
515 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
520 around foo => sub { ... };
522 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
527 after foo => sub { ... };
529 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
532 =head1 SUB QUOTE AWARE
534 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
535 giving us a handy, XS-free speed boost. Any option that is L<Sub::Quote>
536 aware can take advantage of this.
538 =head1 INCOMPATIBILITIES WITH MOOSE
540 There is no built in type system. C<isa> is verified with a coderef, if you
541 need complex types, just make a library of coderefs, or better yet, functions
542 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
543 to L<MooseX::Types::Moose> so that you can write
545 has days_to_live => (is => 'ro', isa => Int);
547 and have it work with both; it is hoped that providing only subrefs as an
548 API will encourage the use of other type systems as well, since it's
549 probably the weakest part of Moose design-wise.
551 C<initializer> is not supported in core since the author considers it to be a
552 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
553 C<coerce> are more likely to be able to fulfill your needs.
555 There is no meta object. If you need this level of complexity you wanted
556 L<Moose> - Moo succeeds at being small because it explicitly does not
557 provide a metaprotocol. However, if you load L<Moose>, then
559 Class::MOP::class_of($moo_class_or_role)
561 will return an appropriate metaclass pre-populated by L<Moo>.
563 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
564 be handled by around albeit with a little more typing, and the author considers
565 augment to be a bad idea.
567 The C<dump> method is not provided by default. The author suggests loading
568 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
569 using C<$obj-E<gt>$::Dwarn()> instead.
571 L</default> only supports coderefs, because doing otherwise is usually a
574 C<lazy_build> is not supported; you are instead encouraged to use the
575 C<is => 'lazy'> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
577 C<auto_deref> is not supported since the author considers it a bad idea.
579 C<documentation> will show up in a L<Moose> metaclass created from your class
580 but is otherwise ignored. Then again, L<Moose> ignors it as well, so this
581 is arguably not an incompatibility.
583 Handling of warnings: when you C<use Moo> we enable FATAL warnings. The nearest
584 similar invocation for L<Moose> would be:
587 use warnings FATAL => "all";
589 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
590 reduce common boilerplate. The set of shortcuts is the same as in the L<Moose>
591 module L<MooseX::AttributeShortcuts> as of its version 0.009+. So if you:
596 The nearest L<Moose> invocation would be:
601 use warnings FATAL => "all";
602 use MooseX::AttributeShortcuts;
604 or, if you're inheriting from a non-Moose class,
609 use MooseX::NonMoose;
610 use warnings FATAL => "all";
611 use MooseX::AttributeShortcuts;
613 Finally, Moose requires you to call
615 __PACKAGE__->meta->make_immutable;
617 at the end of your class to get an inlined (i.e. not horribly slow)
618 constructor. Moo does it automatically the first time ->new is called
623 IRC: #web-simple on irc.perl.org
627 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
631 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
633 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
635 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
637 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
639 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
641 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
643 ajgb - Alex J. G. BurzyĆski (cpan:AJGB) <ajgb@cpan.org>
645 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
647 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
651 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
656 This library is free software and may be distributed under the same terms