8 our $VERSION = '1.000007'; # 1.0.7
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 if ($Moo::Role::INFO{$target} and $Moo::Role::INFO{$target}{is_role}) {
26 die "Cannot import Moo into a role";
28 return if $MAKERS{$target}; # already exported into this package
29 $MAKERS{$target} = { is_class => 1 };
30 _install_tracked $target => extends => sub {
31 $class->_set_superclasses($target, @_);
32 $class->_maybe_reset_handlemoose($target);
35 _install_tracked $target => with => sub {
37 Moo::Role->apply_roles_to_package($target, @_);
38 $class->_maybe_reset_handlemoose($target);
40 _install_tracked $target => has => sub {
41 my ($name_proto, %spec) = @_;
42 my $name_isref = ref $name_proto eq 'ARRAY';
43 foreach my $name ($name_isref ? @$name_proto : $name_proto) {
44 # Note that when $name_proto is an arrayref, each attribute
45 # needs a separate \%specs hashref
46 my $spec_ref = $name_isref ? +{%spec} : \%spec;
47 $class->_constructor_maker_for($target)
48 ->register_attribute_specs($name, $spec_ref);
49 $class->_accessor_maker_for($target)
50 ->generate_method($target, $name, $spec_ref);
51 $class->_maybe_reset_handlemoose($target);
55 foreach my $type (qw(before after around)) {
56 _install_tracked $target => $type => sub {
57 require Class::Method::Modifiers;
58 _install_modifier($target, $type, @_);
64 @{"${target}::ISA"} = do {
65 require Moo::Object; ('Moo::Object');
66 } unless @{"${target}::ISA"};
68 if ($INC{'Moo/HandleMoose.pm'}) {
69 Moo::HandleMoose::inject_fake_metaclass_for($target);
75 _unimport_coderefs($target, $MAKERS{$target});
78 sub _set_superclasses {
81 foreach my $superclass (@_) {
82 _load_module($superclass);
83 if ($INC{"Role/Tiny.pm"} && $Role::Tiny::INFO{$superclass}) {
85 Carp::croak("Can't extend role '$superclass'");
88 # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
89 @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
90 if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
91 delete _getstash($target)->{new};
92 Moo->_constructor_maker_for($target)
93 ->register_attribute_specs(%{$old->all_attribute_specs});
95 no warnings 'once'; # piss off. -- mst
96 $Moo::HandleMoose::MOUSE{$target} = [
97 grep defined, map Mouse::Util::find_meta($_), @_
98 ] if Mouse::Util->can('find_meta');
101 sub _maybe_reset_handlemoose {
102 my ($class, $target) = @_;
103 if ($INC{"Moo/HandleMoose.pm"}) {
104 Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
108 sub _accessor_maker_for {
109 my ($class, $target) = @_;
110 return unless $MAKERS{$target};
111 $MAKERS{$target}{accessor} ||= do {
112 my $maker_class = do {
114 if (my $defer_target =
115 (Sub::Defer::defer_info($target->can('new'))||[])->[0]
117 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
118 $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
125 require Method::Generate::Accessor;
126 'Method::Generate::Accessor'
133 sub _constructor_maker_for {
134 my ($class, $target, $select_super) = @_;
135 return unless $MAKERS{$target};
136 $MAKERS{$target}{constructor} ||= do {
137 require Method::Generate::Constructor;
139 my ($moo_constructor, $con);
141 if ($select_super && $MAKERS{$select_super}) {
142 $moo_constructor = 1;
143 $con = $MAKERS{$select_super}{constructor};
145 my $t_new = $target->can('new');
147 if ($t_new == Moo::Object->can('new')) {
148 $moo_constructor = 1;
149 } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
150 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
152 $moo_constructor = 1;
153 $con = $MAKERS{$pkg}{constructor};
157 $moo_constructor = 1; # no other constructor, make a Moo one
160 ($con ? ref($con) : 'Method::Generate::Constructor')
163 accessor_generator => $class->_accessor_maker_for($target),
164 construction_string => (
166 ? ($con ? $con->construction_string : undef)
167 : ('$class->'.$target.'::SUPER::new(@_)')
169 subconstructor_handler => (
170 ' if ($Moo::MAKERS{$class}) {'."\n"
171 .' '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
172 .' return $class->new(@_)'.";\n"
173 .' } elsif ($INC{"Moose.pm"} and my $meta = Class::MOP::get_metaclass_by_name($class)) {'."\n"
174 .' return $meta->new_object($class->BUILDARGS(@_));'."\n"
179 ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
190 Moo - Minimalist Object Orientation (with Moose compatiblity)
200 my $amount = shift || 1;
202 $self->pounds( $self->pounds - $amount );
212 die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
218 isa => sub { die "$_[0] is too much cat food!" unless $_[0] < 15 },
225 my $full = Cat::Food->new(
226 taste => 'DELICIOUS.',
227 brand => 'SWEET-TREATZ',
237 This module is an extremely light-weight subset of L<Moose> optimised for
238 rapid startup and "pay only for what you use".
240 It also avoids depending on any XS modules to allow simple deployments. The
241 name C<Moo> is based on the idea that it provides almost -- but not quite -- two
244 Unlike L<Mouse> this module does not aim at full compatibility with
245 L<Moose>'s surface syntax, preferring instead of provide full interoperability
246 via the metaclass inflation capabilities described in L</MOO AND MOOSE>.
248 For a full list of the minor differences between L<Moose> and L<Moo>'s surface
249 syntax, see L</INCOMPATIBILITIES WITH MOOSE>.
251 =head1 WHY MOO EXISTS
253 If you want a full object system with a rich Metaprotocol, L<Moose> is
256 However, sometimes you're writing a command line script or a CGI script
257 where fast startup is essential, or code designed to be deployed as a single
258 file via L<App::FatPacker>, or you're writing a CPAN module and you want it
259 to be usable by people with those constraints.
261 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
262 takes longer to load than most of my Moo based CGI scripts take to run.
264 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
265 you want "as little as possible" -- which means "no metaprotocol", which is
268 Better still, if you install and load L<Moose>, we set up metaclasses for your
269 L<Moo> classes and L<Moo::Role> roles, so you can use them in L<Moose> code
270 without ever noticing that some of your codebase is using L<Moo>.
272 Hence, Moo exists as its name -- Minimal Object Orientation -- with a pledge
273 to make it smooth to upgrade to L<Moose> when you need more than minimal
278 If L<Moo> detects L<Moose> being loaded, it will automatically register
279 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
280 to use them in L<Moose> code without anybody ever noticing you aren't using
283 Extending a L<Moose> class or consuming a L<Moose::Role> will also work.
285 So will extending a L<Mouse> class or consuming a L<Mouse::Role> - but note
286 that we don't provide L<Mouse> metaclasses or metaroles so the other way
287 around doesn't work. This feature exists for L<Any::Moose> users porting to
288 L<Moo>; enabling L<Mouse> users to use L<Moo> classes is not a priority for us.
290 This means that there is no need for anything like L<Any::Moose> for Moo
291 code - Moo and Moose code should simply interoperate without problem. To
292 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
293 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
294 metaclasses like L<Moo> does.
296 If you want types to be upgraded to the L<Moose> types, use
297 L<MooX::Types::MooseLike> and install the L<MooseX::Types> library to
298 match the L<MooX::Types::MooseLike> library you're using - L<Moo> will
299 load the L<MooseX::Types> library and use that type for the newly created
302 If you need to disable the metaclass creation, add:
306 to your code before Moose is loaded, but bear in mind that this switch is
307 currently global and turns the mechanism off entirely so don't put this
310 =head1 MOO VERSUS ANY::MOOSE
312 L<Any::Moose> will load L<Mouse> normally, and L<Moose> in a program using
313 L<Moose> - which theoretically allows you to get the startup time of L<Mouse>
314 without disadvantaging L<Moose> users.
316 Sadly, this doesn't entirely work, since the selection is load order dependent
317 - L<Moo>'s metaclass inflation system explained above in L</MOO AND MOOSE> is
318 significantly more reliable.
320 So if you want to write a CPAN module that loads fast or has only pure perl
321 dependencies but is also fully usable by L<Moose> users, you should be using
324 For a full explanation, see the article
325 L<http://shadow.cat/blog/matt-s-trout/moo-versus-any-moose> which explains
326 the differing strategies in more detail and provides a direct example of
327 where L<Moo> succeeds and L<Any::Moose> fails.
329 =head1 IMPORTED METHODS
333 Foo::Bar->new( attr1 => 3 );
337 Foo::Bar->new({ attr1 => 3 });
342 my ( $class, @args ) = @_;
344 unshift @args, "attr1" if @args % 2 == 1;
351 The default implementation of this method accepts a hash or hash reference of
352 named parameters. If it receives a single argument that isn't a hash reference
355 You can override this method in your class to handle other types of options
356 passed to the constructor.
358 This method should always return a hash reference of named options.
362 Define a C<BUILD> method on your class and the constructor will automatically
363 call the C<BUILD> method from parent down to child after the object has
364 been instantiated. Typically this is used for object validation or possibly
369 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
370 a C<DESTROY> method is created on first object construction which will call
371 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
372 method from child upwards to parents.
374 Note that the C<DESTROY> method is created on first construction of an object
375 of your class in order to not add overhead to classes without C<DEMOLISH>
376 methods; this may prove slightly surprising if you try and define your own.
380 if ($foo->does('Some::Role1')) {
384 Returns true if the object composes in the passed role.
386 =head1 IMPORTED SUBROUTINES
390 extends 'Parent::Class';
392 Declares base class. Multiple superclasses can be passed for multiple
393 inheritance (but please use roles instead).
395 Calling extends more than once will REPLACE your superclasses, not add to
396 them like 'use base' would.
404 with 'Some::Role1', 'Some::Role2';
406 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
407 class. An error will be raised if these roles have conflicting methods.
415 Declares an attribute for the class.
417 The options for C<has> are as follows:
423 B<required>, may be C<ro>, C<lazy>, C<rwp> or C<rw>.
425 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
426 a getter only - by defaulting C<reader> to the name of the attribute.
428 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
429 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
430 attributes. This feature was my attempt to fix my incompetence when
431 originally designing C<lazy_build>, and is also implemented by
432 L<MooseX::AttributeShortcuts>.
434 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
435 C<_set_${attribute_name}> for attributes that are designed to be written
436 from inside of the class, but read-only from outside.
437 This feature comes from L<MooseX::AttributeShortcuts>.
439 C<rw> generates a normal getter/setter by defaulting C<accessor> to the
440 name of the attribute.
444 Takes a coderef which is meant to validate the attribute. Unlike L<Moose>, Moo
445 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
449 die "$_[0] is not a number!" unless looks_like_number $_[0]
452 L<Sub::Quote aware|/SUB QUOTE AWARE>
454 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
455 subroutine has been supplied, C<isa> checks are not structural to your code
456 and can, if desired, be omitted on non-debug builds (although if this results
457 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
458 nothing except that you get to keep both halves).
460 If you want L<MooseX::Types> style named types, look at
461 L<MooX::Types::MooseLike>.
463 To cause your C<isa> entries to be automatically mapped to named
464 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
465 of creating an anonymous type), set:
467 $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
468 require MooseX::Types::Something;
469 return MooseX::Types::Something::TypeName();
472 Note that this example is purely illustrative; anything that returns a
473 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
474 make L<Moose> happy is fine.
478 Takes a coderef which is meant to coerce the attribute. The basic idea is to
479 do something like the following:
482 $_[0] + 1 unless $_[0] % 2
485 Note that L<Moo> will always fire your coercion: this is to permit
486 C<isa> entries to be used purely for bug trapping, whereas coercions are
487 always structural to your code. We do, however, apply any supplied C<isa>
488 check after the coercion has run to ensure that it returned a valid value.
490 L<Sub::Quote aware|/SUB QUOTE AWARE>
496 handles => 'RobotRole'
498 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
499 becomes the list of methods to handle.
501 Takes a list of methods
503 handles => [ qw( one two ) ]
513 Takes a coderef which will get called any time the attribute is set. This
514 includes the constructor. Coderef will be invoked against the object with the
515 new value as an argument.
517 If you set this to just C<1>, it generates a trigger which calls the
518 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
519 L<MooseX::AttributeShortcuts>.
521 Note that Moose also passes the old value, if any; this feature is not yet
524 L<Sub::Quote aware|/SUB QUOTE AWARE>
528 Takes a coderef which will get called with $self as its only argument
529 to populate an attribute if no value is supplied to the constructor - or
530 if the attribute is lazy, when the attribute is first retrieved if no
531 value has yet been provided.
533 Note that if your default is fired during new() there is no guarantee that
534 other attributes have been populated yet so you should not rely on their
537 L<Sub::Quote aware|/SUB QUOTE AWARE>
541 Takes a method name which will return true if an attribute has a value.
543 If you set this to just C<1>, the predicate is automatically named
544 C<has_${attr_name}> if your attribute's name does not start with an
545 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
546 This feature comes from L<MooseX::AttributeShortcuts>.
550 Takes a method name which will be called to create the attribute - functions
551 exactly like default except that instead of calling
559 If you set this to just C<1>, the builder is automatically named
560 C<_build_${attr_name}>. This feature comes from L<MooseX::AttributeShortcuts>.
564 Takes a method name which will clear the attribute.
566 If you set this to just C<1>, the clearer is automatically named
567 C<clear_${attr_name}> if your attribute's name does not start with an
568 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
569 This feature comes from L<MooseX::AttributeShortcuts>.
573 B<Boolean>. Set this if you want values for the attribute to be grabbed
574 lazily. This is usually a good idea if you have a L</builder> which requires
575 another attribute to be set.
579 B<Boolean>. Set this if the attribute must be passed on instantiation.
583 The value of this attribute will be the name of the method to get the value of
584 the attribute. If you like Java style methods, you might set this to
589 The value of this attribute will be the name of the method to set the value of
590 the attribute. If you like Java style methods, you might set this to
595 B<Boolean>. Set this if you want the reference that the attribute contains to
596 be weakened; use this when circular references are possible, which will cause
601 Takes the name of the key to look for at instantiation time of the object. A
602 common use of this is to make an underscored attribute have a non-underscored
603 initialization name. C<undef> means that passing the value in on instantiation
610 before foo => sub { ... };
612 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
617 around foo => sub { ... };
619 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
624 after foo => sub { ... };
626 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
629 =head1 SUB QUOTE AWARE
631 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
632 giving us a handy, XS-free speed boost. Any option that is L<Sub::Quote>
633 aware can take advantage of this.
635 To do this, you can write
642 isa => quote_sub(q{ die "Not <3" unless $_[0] < 3 })
645 which will be inlined as
648 local @_ = ($_[0]->{foo});
649 die "Not <3" unless $_[0] < 3;
652 or to avoid localizing @_,
656 isa => quote_sub(q{ my ($val) = @_; die "Not <3" unless $val < 3 })
659 which will be inlined as
662 my ($val) = ($_[0]->{foo});
663 die "Not <3" unless $val < 3;
666 See L<Sub::Quote> for more information, including how to pass lexical
667 captures that will also be compiled into the subroutine.
669 =head1 INCOMPATIBILITIES WITH MOOSE
671 There is no built-in type system. C<isa> is verified with a coderef; if you
672 need complex types, just make a library of coderefs, or better yet, functions
673 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
674 to L<MooseX::Types::Moose> so that you can write
676 has days_to_live => (is => 'ro', isa => Int);
678 and have it work with both; it is hoped that providing only subrefs as an
679 API will encourage the use of other type systems as well, since it's
680 probably the weakest part of Moose design-wise.
682 C<initializer> is not supported in core since the author considers it to be a
683 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
684 C<coerce> are more likely to be able to fulfill your needs.
686 There is no meta object. If you need this level of complexity you wanted
687 L<Moose> - Moo succeeds at being small because it explicitly does not
688 provide a metaprotocol. However, if you load L<Moose>, then
690 Class::MOP::class_of($moo_class_or_role)
692 will return an appropriate metaclass pre-populated by L<Moo>.
694 No support for C<super>, C<override>, C<inner>, or C<augment> - the author
695 considers augment to be a bad idea, and override can be translated:
697 override foo => sub {
704 my ($orig, $self) = (shift, shift);
710 The C<dump> method is not provided by default. The author suggests loading
711 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
712 using C<$obj-E<gt>$::Dwarn()> instead.
714 L</default> only supports coderefs, because doing otherwise is usually a
717 C<lazy_build> is not supported; you are instead encouraged to use the
718 C<< is => 'lazy' >> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
720 C<auto_deref> is not supported since the author considers it a bad idea.
722 C<documentation> will show up in a L<Moose> metaclass created from your class
723 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
724 is arguably not an incompatibility.
726 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
727 require it, the metaclass inflation for coerce alone is a trifle insane
728 and if you attempt to subtype the result will almost certainly break.
730 Handling of warnings: when you C<use Moo> we enable FATAL warnings. The nearest
731 similar invocation for L<Moose> would be:
734 use warnings FATAL => "all";
736 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
737 reduce common boilerplate. The set of shortcuts is the same as in the L<Moose>
738 module L<MooseX::AttributeShortcuts> as of its version 0.009+. So if you:
743 The nearest L<Moose> invocation would be:
748 use warnings FATAL => "all";
749 use MooseX::AttributeShortcuts;
751 or, if you're inheriting from a non-Moose class,
756 use MooseX::NonMoose;
757 use warnings FATAL => "all";
758 use MooseX::AttributeShortcuts;
760 Finally, Moose requires you to call
762 __PACKAGE__->meta->make_immutable;
764 at the end of your class to get an inlined (i.e. not horribly slow)
765 constructor. Moo does it automatically the first time ->new is called
768 An extension L<MooX::late> exists to ease translating Moose packages
769 to Moo by providing a more Moose-like interface.
773 Users' IRC: #moose on irc.perl.org
775 Development and contribution IRC: #web-simple on irc.perl.org
779 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
783 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
785 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
787 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
789 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
791 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
793 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
795 ajgb - Alex J. G. Burzyński (cpan:AJGB) <ajgb@cpan.org>
797 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
799 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
801 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
803 ilmari - Dagfinn Ilmari Mannsåker (cpan:ILMARI) <ilmari@ilmari.org>
805 tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
809 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
814 This library is free software and may be distributed under the same terms