8 our $VERSION = '1.000006'; # 1.0.6
9 $VERSION = eval $VERSION;
11 require Moo::sification;
15 sub _install_tracked {
16 my ($target, $name, $code) = @_;
17 $MAKERS{$target}{exports}{$name} = $code;
18 _install_coderef "${target}::${name}" => "Moo::${name}" => $code;
25 return if $MAKERS{$target}; # already exported into this package
26 $MAKERS{$target} = {};
27 _install_tracked $target => extends => sub {
28 $class->_set_superclasses($target, @_);
29 $class->_maybe_reset_handlemoose($target);
32 _install_tracked $target => with => sub {
34 Moo::Role->apply_roles_to_package($target, @_);
35 $class->_maybe_reset_handlemoose($target);
37 _install_tracked $target => has => sub {
38 my ($name_proto, %spec) = @_;
39 my $name_isref = ref $name_proto eq 'ARRAY';
40 foreach my $name ($name_isref ? @$name_proto : $name_proto) {
41 # Note that when $name_proto is an arrayref, each attribute
42 # needs a separate \%specs hashref
43 my $spec_ref = $name_isref ? +{%spec} : \%spec;
44 $class->_constructor_maker_for($target)
45 ->register_attribute_specs($name, $spec_ref);
46 $class->_accessor_maker_for($target)
47 ->generate_method($target, $name, $spec_ref);
48 $class->_maybe_reset_handlemoose($target);
52 foreach my $type (qw(before after around)) {
53 _install_tracked $target => $type => sub {
54 require Class::Method::Modifiers;
55 _install_modifier($target, $type, @_);
61 @{"${target}::ISA"} = do {
62 require Moo::Object; ('Moo::Object');
63 } unless @{"${target}::ISA"};
65 if ($INC{'Moo/HandleMoose.pm'}) {
66 Moo::HandleMoose::inject_fake_metaclass_for($target);
72 _unimport_coderefs($target, $MAKERS{$target});
75 sub _set_superclasses {
78 foreach my $superclass (@_) {
79 _load_module($superclass);
80 if ($INC{"Role/Tiny.pm"} && $Role::Tiny::INFO{$superclass}) {
82 Carp::croak("Can't extend role '$superclass'");
85 # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
86 @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
87 if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
88 delete _getstash($target)->{new};
89 Moo->_constructor_maker_for($target)
90 ->register_attribute_specs(%{$old->all_attribute_specs});
92 no warnings 'once'; # piss off. -- mst
93 $Moo::HandleMoose::MOUSE{$target} = [
94 grep defined, map Mouse::Util::find_meta($_), @_
95 ] if $INC{"Mouse.pm"};
98 sub _maybe_reset_handlemoose {
99 my ($class, $target) = @_;
100 if ($INC{"Moo/HandleMoose.pm"}) {
101 Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
105 sub _accessor_maker_for {
106 my ($class, $target) = @_;
107 return unless $MAKERS{$target};
108 $MAKERS{$target}{accessor} ||= do {
109 my $maker_class = do {
111 if (my $defer_target =
112 (Sub::Defer::defer_info($target->can('new'))||[])->[0]
114 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
115 $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
122 require Method::Generate::Accessor;
123 'Method::Generate::Accessor'
130 sub _constructor_maker_for {
131 my ($class, $target, $select_super) = @_;
132 return unless $MAKERS{$target};
133 $MAKERS{$target}{constructor} ||= do {
134 require Method::Generate::Constructor;
136 my ($moo_constructor, $con);
138 if ($select_super && $MAKERS{$select_super}) {
139 $moo_constructor = 1;
140 $con = $MAKERS{$select_super}{constructor};
142 my $t_new = $target->can('new');
144 if ($t_new == Moo::Object->can('new')) {
145 $moo_constructor = 1;
146 } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
147 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
149 $moo_constructor = 1;
150 $con = $MAKERS{$pkg}{constructor};
154 $moo_constructor = 1; # no other constructor, make a Moo one
157 ($con ? ref($con) : 'Method::Generate::Constructor')
160 accessor_generator => $class->_accessor_maker_for($target),
161 construction_string => (
163 ? ($con ? $con->construction_string : undef)
164 : ('$class->'.$target.'::SUPER::new(@_)')
166 subconstructor_handler => (
167 ' if ($Moo::MAKERS{$class}) {'."\n"
168 .' '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
169 .' return $class->new(@_)'.";\n"
170 .' } elsif ($INC{"Moose.pm"} and my $meta = Class::MOP::get_metaclass_by_name($class)) {'."\n"
171 .' return $meta->new_object($class->BUILDARGS(@_));'."\n"
176 ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
187 Moo - Minimalist Object Orientation (with Moose compatiblity)
197 my $amount = shift || 1;
199 $self->pounds( $self->pounds - $amount );
209 die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
215 isa => sub { die "$_[0] is too much cat food!" unless $_[0] < 15 },
222 my $full = Cat::Food->new(
223 taste => 'DELICIOUS.',
224 brand => 'SWEET-TREATZ',
234 This module is an extremely light-weight subset of L<Moose> optimised for
235 rapid startup and "pay only for what you use".
237 It also avoids depending on any XS modules to allow simple deployments. The
238 name C<Moo> is based on the idea that it provides almost -- but not quite -- two
241 Unlike L<Mouse> this module does not aim at full compatibility with
242 L<Moose>'s surface syntax, preferring instead of provide full interoperability
243 via the metaclass inflation capabilities described in L</MOO AND MOOSE>.
245 For a full list of the minor differences between L<Moose> and L<Moo>'s surface
246 syntax, see L</INCOMPATIBILITIES WITH MOOSE>.
248 =head1 WHY MOO EXISTS
250 If you want a full object system with a rich Metaprotocol, L<Moose> is
253 However, sometimes you're writing a command line script or a CGI script
254 where fast startup is essential, or code designed to be deployed as a single
255 file via L<App::FatPacker>, or you're writing a CPAN module and you want it
256 to be usable by people with those constraints.
258 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
259 takes longer to load than most of my Moo based CGI scripts take to run.
261 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
262 you want "as little as possible" -- which means "no metaprotocol", which is
265 Better still, if you install and load L<Moose>, we set up metaclasses for your
266 L<Moo> classes and L<Moo::Role> roles, so you can use them in L<Moose> code
267 without ever noticing that some of your codebase is using L<Moo>.
269 Hence, Moo exists as its name -- Minimal Object Orientation -- with a pledge
270 to make it smooth to upgrade to L<Moose> when you need more than minimal
275 If L<Moo> detects L<Moose> being loaded, it will automatically register
276 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
277 to use them in L<Moose> code without anybody ever noticing you aren't using
280 Extending a L<Moose> class or consuming a L<Moose::Role> will also work.
282 So will extending a L<Mouse> class or consuming a L<Mouse::Role> - but note
283 that we don't provide L<Mouse> metaclasses or metaroles so the other way
284 around doesn't work. This feature exists for L<Any::Moose> users porting to
285 L<Moo>; enabling L<Mouse> users to use L<Moo> classes is not a priority for us.
287 This means that there is no need for anything like L<Any::Moose> for Moo
288 code - Moo and Moose code should simply interoperate without problem. To
289 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
290 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
291 metaclasses like L<Moo> does.
293 If you want types to be upgraded to the L<Moose> types, use
294 L<MooX::Types::MooseLike> and install the L<MooseX::Types> library to
295 match the L<MooX::Types::MooseLike> library you're using - L<Moo> will
296 load the L<MooseX::Types> library and use that type for the newly created
299 If you need to disable the metaclass creation, add:
303 to your code before Moose is loaded, but bear in mind that this switch is
304 currently global and turns the mechanism off entirely so don't put this
307 =head1 MOO VERSUS ANY::MOOSE
309 L<Any::Moose> will load L<Mouse> normally, and L<Moose> in a program using
310 L<Moose> - which theoretically allows you to get the startup time of L<Mouse>
311 without disadvantaging L<Moose> users.
313 Sadly, this doesn't entirely work, since the selection is load order dependent
314 - L<Moo>'s metaclass inflation system explained above in L</MOO AND MOOSE> is
315 significantly more reliable.
317 So if you want to write a CPAN module that loads fast or has only pure perl
318 dependencies but is also fully usable by L<Moose> users, you should be using
321 For a full explanation, see the article
322 L<http://shadow.cat/blog/matt-s-trout/moo-versus-any-moose> which explains
323 the differing strategies in more detail and provides a direct example of
324 where L<Moo> succeeds and L<Any::Moose> fails.
326 =head1 IMPORTED METHODS
330 Foo::Bar->new( attr1 => 3 );
334 Foo::Bar->new({ attr1 => 3 });
339 my ( $class, @args ) = @_;
341 unshift @args, "attr1" if @args % 2 == 1;
348 The default implementation of this method accepts a hash or hash reference of
349 named parameters. If it receives a single argument that isn't a hash reference
352 You can override this method in your class to handle other types of options
353 passed to the constructor.
355 This method should always return a hash reference of named options.
359 Define a C<BUILD> method on your class and the constructor will automatically
360 call the C<BUILD> method from parent down to child after the object has
361 been instantiated. Typically this is used for object validation or possibly
366 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
367 a C<DESTROY> method is created on first object construction which will call
368 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
369 method from child upwards to parents.
371 Note that the C<DESTROY> method is created on first construction of an object
372 of your class in order to not add overhead to classes without C<DEMOLISH>
373 methods; this may prove slightly surprising if you try and define your own.
377 if ($foo->does('Some::Role1')) {
381 Returns true if the object composes in the passed role.
383 =head1 IMPORTED SUBROUTINES
387 extends 'Parent::Class';
389 Declares base class. Multiple superclasses can be passed for multiple
390 inheritance (but please use roles instead).
392 Calling extends more than once will REPLACE your superclasses, not add to
393 them like 'use base' would.
401 with 'Some::Role1', 'Some::Role2';
403 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
404 class. An error will be raised if these roles have conflicting methods.
412 Declares an attribute for the class.
414 The options for C<has> are as follows:
420 B<required>, may be C<ro>, C<lazy>, C<rwp> or C<rw>.
422 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
423 a getter only - by defaulting C<reader> to the name of the attribute.
425 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
426 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
427 attributes. This feature was my attempt to fix my incompetence when
428 originally designing C<lazy_build>, and is also implemented by
429 L<MooseX::AttributeShortcuts>.
431 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
432 C<_set_${attribute_name}> for attributes that are designed to be written
433 from inside of the class, but read-only from outside.
434 This feature comes from L<MooseX::AttributeShortcuts>.
436 C<rw> generates a normal getter/setter by defaulting C<accessor> to the
437 name of the attribute.
441 Takes a coderef which is meant to validate the attribute. Unlike L<Moose>, Moo
442 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
446 die "$_[0] is not a number!" unless looks_like_number $_[0]
449 L<Sub::Quote aware|/SUB QUOTE AWARE>
451 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
452 subroutine has been supplied, C<isa> checks are not structural to your code
453 and can, if desired, be omitted on non-debug builds (although if this results
454 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
455 nothing except that you get to keep both halves).
457 If you want L<MooseX::Types> style named types, look at
458 L<MooX::Types::MooseLike>.
460 To cause your C<isa> entries to be automatically mapped to named
461 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
462 of creating an anonymous type), set:
464 $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
465 require MooseX::Types::Something;
466 return MooseX::Types::Something::TypeName();
469 Note that this example is purely illustrative; anything that returns a
470 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
471 make L<Moose> happy is fine.
475 Takes a coderef which is meant to coerce the attribute. The basic idea is to
476 do something like the following:
479 $_[0] + 1 unless $_[0] % 2
482 Note that L<Moo> will always fire your coercion: this is to permit
483 C<isa> entries to be used purely for bug trapping, whereas coercions are
484 always structural to your code. We do, however, apply any supplied C<isa>
485 check after the coercion has run to ensure that it returned a valid value.
487 L<Sub::Quote aware|/SUB QUOTE AWARE>
493 handles => 'RobotRole'
495 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
496 becomes the list of methods to handle.
498 Takes a list of methods
500 handles => [ qw( one two ) ]
510 Takes a coderef which will get called any time the attribute is set. This
511 includes the constructor. Coderef will be invoked against the object with the
512 new value as an argument.
514 If you set this to just C<1>, it generates a trigger which calls the
515 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
516 L<MooseX::AttributeShortcuts>.
518 Note that Moose also passes the old value, if any; this feature is not yet
521 L<Sub::Quote aware|/SUB QUOTE AWARE>
525 Takes a coderef which will get called with $self as its only argument
526 to populate an attribute if no value is supplied to the constructor - or
527 if the attribute is lazy, when the attribute is first retrieved if no
528 value has yet been provided.
530 Note that if your default is fired during new() there is no guarantee that
531 other attributes have been populated yet so you should not rely on their
534 L<Sub::Quote aware|/SUB QUOTE AWARE>
538 Takes a method name which will return true if an attribute has a value.
540 If you set this to just C<1>, the predicate is automatically named
541 C<has_${attr_name}> if your attribute's name does not start with an
542 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
543 This feature comes from L<MooseX::AttributeShortcuts>.
547 Takes a method name which will be called to create the attribute - functions
548 exactly like default except that instead of calling
556 If you set this to just C<1>, the predicate is automatically named
557 C<_build_${attr_name}>. This feature comes from L<MooseX::AttributeShortcuts>.
561 Takes a method name which will clear the attribute.
563 If you set this to just C<1>, the clearer is automatically named
564 C<clear_${attr_name}> if your attribute's name does not start with an
565 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
566 This feature comes from L<MooseX::AttributeShortcuts>.
570 B<Boolean>. Set this if you want values for the attribute to be grabbed
571 lazily. This is usually a good idea if you have a L</builder> which requires
572 another attribute to be set.
576 B<Boolean>. Set this if the attribute must be passed on instantiation.
580 The value of this attribute will be the name of the method to get the value of
581 the attribute. If you like Java style methods, you might set this to
586 The value of this attribute will be the name of the method to set the value of
587 the attribute. If you like Java style methods, you might set this to
592 B<Boolean>. Set this if you want the reference that the attribute contains to
593 be weakened; use this when circular references are possible, which will cause
598 Takes the name of the key to look for at instantiation time of the object. A
599 common use of this is to make an underscored attribute have a non-underscored
600 initialization name. C<undef> means that passing the value in on instantiation
607 before foo => sub { ... };
609 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
614 around foo => sub { ... };
616 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
621 after foo => sub { ... };
623 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
626 =head1 SUB QUOTE AWARE
628 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
629 giving us a handy, XS-free speed boost. Any option that is L<Sub::Quote>
630 aware can take advantage of this.
632 To do this, you can write
639 isa => quote_sub(q{ die "Not <3" unless $_[0] < 3 })
642 which will be inlined as
645 local @_ = ($_[0]->{foo});
646 die "Not <3" unless $_[0] < 3;
649 or to avoid localizing @_,
653 isa => quote_sub(q{ my ($val) = @_; die "Not <3" unless $val < 3 })
656 which will be inlined as
659 my ($val) = ($_[0]->{foo});
660 die "Not <3" unless $val < 3;
663 See L<Sub::Quote> for more information, including how to pass lexical
664 captures that will also be compiled into the subroutine.
666 =head1 INCOMPATIBILITIES WITH MOOSE
668 There is no built-in type system. C<isa> is verified with a coderef; if you
669 need complex types, just make a library of coderefs, or better yet, functions
670 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
671 to L<MooseX::Types::Moose> so that you can write
673 has days_to_live => (is => 'ro', isa => Int);
675 and have it work with both; it is hoped that providing only subrefs as an
676 API will encourage the use of other type systems as well, since it's
677 probably the weakest part of Moose design-wise.
679 C<initializer> is not supported in core since the author considers it to be a
680 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
681 C<coerce> are more likely to be able to fulfill your needs.
683 There is no meta object. If you need this level of complexity you wanted
684 L<Moose> - Moo succeeds at being small because it explicitly does not
685 provide a metaprotocol. However, if you load L<Moose>, then
687 Class::MOP::class_of($moo_class_or_role)
689 will return an appropriate metaclass pre-populated by L<Moo>.
691 No support for C<super>, C<override>, C<inner>, or C<augment> - the author
692 considers augment to be a bad idea, and override can be translated:
694 override foo => sub {
701 my ($orig, $self) = (shift, shift);
707 The C<dump> method is not provided by default. The author suggests loading
708 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
709 using C<$obj-E<gt>$::Dwarn()> instead.
711 L</default> only supports coderefs, because doing otherwise is usually a
714 C<lazy_build> is not supported; you are instead encouraged to use the
715 C<< is => 'lazy' >> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
717 C<auto_deref> is not supported since the author considers it a bad idea.
719 C<documentation> will show up in a L<Moose> metaclass created from your class
720 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
721 is arguably not an incompatibility.
723 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
724 require it, the metaclass inflation for coerce alone is a trifle insane
725 and if you attempt to subtype the result will almost certainly break.
727 Handling of warnings: when you C<use Moo> we enable FATAL warnings. The nearest
728 similar invocation for L<Moose> would be:
731 use warnings FATAL => "all";
733 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
734 reduce common boilerplate. The set of shortcuts is the same as in the L<Moose>
735 module L<MooseX::AttributeShortcuts> as of its version 0.009+. So if you:
740 The nearest L<Moose> invocation would be:
745 use warnings FATAL => "all";
746 use MooseX::AttributeShortcuts;
748 or, if you're inheriting from a non-Moose class,
753 use MooseX::NonMoose;
754 use warnings FATAL => "all";
755 use MooseX::AttributeShortcuts;
757 Finally, Moose requires you to call
759 __PACKAGE__->meta->make_immutable;
761 at the end of your class to get an inlined (i.e. not horribly slow)
762 constructor. Moo does it automatically the first time ->new is called
767 Users' IRC: #moose on irc.perl.org
769 Development and contribution IRC: #web-simple on irc.perl.org
773 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
777 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
779 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
781 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
783 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
785 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
787 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
789 ajgb - Alex J. G. Burzyński (cpan:AJGB) <ajgb@cpan.org>
791 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
793 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
795 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
797 ilmari - Dagfinn Ilmari Mannsåker (cpan:ILMARI) <ilmari@ilmari.org>
799 tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
803 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
808 This library is free software and may be distributed under the same terms