8 our $VERSION = '0.091014'; # 0.91.14
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, %spec) = @_;
39 $class->_constructor_maker_for($target)
40 ->register_attribute_specs($name, \%spec);
41 $class->_accessor_maker_for($target)
42 ->generate_method($target, $name, \%spec);
43 $class->_maybe_reset_handlemoose($target);
46 foreach my $type (qw(before after around)) {
47 _install_tracked $target => $type => sub {
48 require Class::Method::Modifiers;
49 _install_modifier($target, $type, @_);
55 @{"${target}::ISA"} = do {
56 require Moo::Object; ('Moo::Object');
57 } unless @{"${target}::ISA"};
59 if ($INC{'Moo/HandleMoose.pm'}) {
60 Moo::HandleMoose::inject_fake_metaclass_for($target);
66 _unimport_coderefs($target, $MAKERS{$target});
69 sub _set_superclasses {
74 if ($INC{"Role/Tiny.pm"} && $Role::Tiny::INFO{$_}) {
76 Carp::croak("Can't extend role '$_'");
79 # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
80 @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
81 if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
82 delete _getstash($target)->{new};
83 Moo->_constructor_maker_for($target)
84 ->register_attribute_specs(%{$old->all_attribute_specs});
86 no warnings 'once'; # piss off. -- mst
87 $Moo::HandleMoose::MOUSE{$target} = [
88 grep defined, map Mouse::Util::find_meta($_), @_
89 ] if $INC{"Mouse.pm"};
92 sub _maybe_reset_handlemoose {
93 my ($class, $target) = @_;
94 if ($INC{"Moo/HandleMoose.pm"}) {
95 Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
99 sub _accessor_maker_for {
100 my ($class, $target) = @_;
101 return unless $MAKERS{$target};
102 $MAKERS{$target}{accessor} ||= do {
103 my $maker_class = do {
105 if (my $defer_target =
106 (Sub::Defer::defer_info($target->can('new'))||[])->[0]
108 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
109 $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
116 require Method::Generate::Accessor;
117 'Method::Generate::Accessor'
124 sub _constructor_maker_for {
125 my ($class, $target, $select_super) = @_;
126 return unless $MAKERS{$target};
127 $MAKERS{$target}{constructor} ||= do {
128 require Method::Generate::Constructor;
130 my ($moo_constructor, $con);
132 if ($select_super && $MAKERS{$select_super}) {
133 $moo_constructor = 1;
134 $con = $MAKERS{$select_super}{constructor};
136 my $t_new = $target->can('new');
138 if ($t_new == Moo::Object->can('new')) {
139 $moo_constructor = 1;
140 } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
141 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
143 $moo_constructor = 1;
144 $con = $MAKERS{$pkg}{constructor};
148 $moo_constructor = 1; # no other constructor, make a Moo one
151 ($con ? ref($con) : 'Method::Generate::Constructor')
154 accessor_generator => $class->_accessor_maker_for($target),
155 construction_string => (
157 ? ($con ? $con->construction_string : undef)
158 : ('$class->'.$target.'::SUPER::new(@_)')
160 subconstructor_handler => (
161 ' if ($Moo::MAKERS{$class}) {'."\n"
162 .' '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
163 .' return $class->new(@_)'.";\n"
164 .' } elsif ($INC{"Moose.pm"} and my $meta = Class::MOP::get_metaclass_by_name($class)) {'."\n"
165 .' return $meta->new_object(@_);'."\n"
170 ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
181 Moo - Minimalist Object Orientation (with Moose compatiblity)
192 my $amount = shift || 1;
194 $self->pounds( $self->pounds - $amount );
204 die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
210 isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
217 my $full = Cat::Food->new(
218 taste => 'DELICIOUS.',
219 brand => 'SWEET-TREATZ',
229 This module is an extremely light-weight, high-performance L<Moose> replacement.
230 It also avoids depending on any XS modules to allow simple deployments. The
231 name C<Moo> is based on the idea that it provides almost -but not quite- two
234 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility. See
235 L</INCOMPATIBILITIES> for more details.
237 =head1 WHY MOO EXISTS
239 If you want a full object system with a rich Metaprotocol, L<Moose> is
242 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
243 takes longer to load than most of my Moo based CGI scripts take to run.
245 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
246 you want "as little as possible" - which means "no metaprotocol", which is
249 By Moo 1.0 I intend to have Moo's equivalent of L<Any::Moose> built in -
250 if Moose gets loaded, any Moo class or role will act as a Moose equivalent
253 Hence - Moo exists as its name - Minimal Object Orientation - with a pledge
254 to make it smooth to upgrade to L<Moose> when you need more than minimal
257 =head1 Moo and Moose - NEW, EXPERIMENTAL
259 If L<Moo> detects L<Moose> being loaded, it will automatically register
260 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
261 to use them in L<Moose> code without it ever realising you aren't using
264 Extending a L<Moose> class or consuming a L<Moose::Role> should also work.
266 So should extending a L<Mouse> class or consuming a L<Mouse::Role>.
268 This means that there is no need for anything like L<Any::Moose> for Moo
269 code - Moo and Moose code should simply interoperate without problem. To
270 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
271 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
272 metaclasses like we do.
274 However, these features are new as of 0.91.0 (0.091000) so while serviceable,
275 they are absolutely certain to not be 100% yet; please do report bugs.
277 If you need to disable the metaclass creation, add:
281 to your code before Moose is loaded, but bear in mind that this switch is
282 currently global and turns the mechanism off entirely, so don't put this
283 in library code, only in a top level script as a temporary measure while
284 you send a bug report.
286 =head1 IMPORTED METHODS
290 Foo::Bar->new( attr1 => 3 );
294 Foo::Bar->new({ attr1 => 3 });
299 my ( $class, @args ) = @_;
301 unshift @args, "attr1" if @args % 2 == 1;
308 The default implementation of this method accepts a hash or hash reference of
309 named parameters. If it receives a single argument that isn't a hash reference
312 You can override this method in your class to handle other types of options
313 passed to the constructor.
315 This method should always return a hash reference of named options.
319 Define a C<BUILD> method on your class and the constructor will automatically
320 call the C<BUILD> method from parent down to child after the object has
321 been instantiated. Typically this is used for object validation or possibly
326 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
327 a C<DESTROY> method is created on first object construction which will call
328 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
329 method from child upwards to parents.
331 Note that the C<DESTROY> method is created on first construction of an object
332 of your class in order to not add overhead to classes without C<DEMOLISH>
333 methods; this may prove slightly surprising if you try and define your own.
337 if ($foo->does('Some::Role1')) {
341 Returns true if the object composes in the passed role.
343 =head1 IMPORTED SUBROUTINES
347 extends 'Parent::Class';
349 Declares base class. Multiple superclasses can be passed for multiple
350 inheritance (but please use roles instead).
352 Calling extends more than once will REPLACE your superclasses, not add to
353 them like 'use base' would.
361 with 'Some::Role1', 'Some::Role2';
363 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
364 class. An error will be raised if these roles have conflicting methods.
372 Declares an attribute for the class.
374 The options for C<has> are as follows:
380 B<required>, may be C<ro>, C<lazy>, C<rwp> or C<rw>.
382 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
383 a getter only - by defaulting C<reader> to the name of the attribute.
385 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
386 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
387 attributes. This feature was my attempt to fix my incompetence when
388 originally designing C<lazy_build>, and is also implemented by
389 L<MooseX::AttributeShortcuts>.
391 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
392 C<_set_${attribute_name}> for attributes that are designed to be written
393 from inside of the class, but read-only from outside.
394 This feature comes from L<MooseX::AttributeShortcuts>.
396 C<rw> generates a normal getter/setter by defaulting C<accessor> to the
397 name of the attribute.
401 Takes a coderef which is meant to validate the attribute. Unlike L<Moose> Moo
402 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
406 die "$_[0] is not a number!" unless looks_like_number $_[0]
409 L<Sub::Quote aware|/SUB QUOTE AWARE>
411 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
412 subroutine has been supplied, C<isa> checks are not structural to your code
413 and can, if desired, be omitted on non-debug builds (although if this results
414 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
415 nothing except that you get to keep both halves).
417 If you want L<MooseX::Types> style named types, look at
418 L<MooX::Types::MooseLike>.
420 To cause your C<isa> entries to be automatically mapped to named
421 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
422 of creating an anonymous type), set:
424 $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
425 require MooseX::Types::Something;
426 return MooseX::Types::Something::TypeName();
429 Note that this example is purely illustrative; anything that returns a
430 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
431 make L<Moose> happy is fine.
435 Takes a coderef which is meant to coerce the attribute. The basic idea is to
436 do something like the following:
438 coerce => quote_sub q{
439 $_[0] + 1 unless $_[0] % 2
442 Note that L<Moo> will always fire your coercion - this is to permit
443 isa entries to be used purely for bug trapping, whereas coercions are
444 always structural to your code. We do, however, apply any supplied C<isa>
445 check after the coercion has run to ensure that it returned a valid value.
447 L<Sub::Quote aware|/SUB QUOTE AWARE>
453 handles => 'RobotRole'
455 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
456 becomes the list of methods to handle.
458 Takes a list of methods
460 handles => [ qw( one two ) ]
470 Takes a coderef which will get called any time the attribute is set. This
471 includes the constructor. Coderef will be invoked against the object with the
472 new value as an argument.
474 If you set this to just C<1>, it generates a trigger which calls the
475 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
476 L<MooseX::AttributeShortcuts>.
478 Note that Moose also passes the old value, if any; this feature is not yet
481 L<Sub::Quote aware|/SUB QUOTE AWARE>
485 Takes a coderef which will get called with $self as its only argument
486 to populate an attribute if no value is supplied to the constructor - or
487 if the attribute is lazy, when the attribute is first retrieved if no
488 value has yet been provided.
490 Note that if your default is fired during new() there is no guarantee that
491 other attributes have been populated yet so you should not rely on their
494 L<Sub::Quote aware|/SUB QUOTE AWARE>
498 Takes a method name which will return true if an attribute has a value.
500 If you set this to just C<1>, the predicate is automatically named
501 C<has_${attr_name}> if your attribute's name does not start with an
502 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
503 This feature comes from L<MooseX::AttributeShortcuts>.
507 Takes a method name which will be called to create the attribute - functions
508 exactly like default except that instead of calling
516 If you set this to just C<1>, the predicate is automatically named
517 C<_build_${attr_name}>. This feature comes from L<MooseX::AttributeShortcuts>.
521 Takes a method name which will clear the attribute.
523 If you set this to just C<1>, the clearer is automatically named
524 C<clear_${attr_name}> if your attribute's name does not start with an
525 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
526 This feature comes from L<MooseX::AttributeShortcuts>.
530 B<Boolean>. Set this if you want values for the attribute to be grabbed
531 lazily. This is usually a good idea if you have a L</builder> which requires
532 another attribute to be set.
536 B<Boolean>. Set this if the attribute must be passed on instantiation.
540 The value of this attribute will be the name of the method to get the value of
541 the attribute. If you like Java style methods, you might set this to
546 The value of this attribute will be the name of the method to set the value of
547 the attribute. If you like Java style methods, you might set this to
552 B<Boolean>. Set this if you want the reference that the attribute contains to
553 be weakened; use this when circular references are possible, which will cause
558 Takes the name of the key to look for at instantiation time of the object. A
559 common use of this is to make an underscored attribute have a non-underscored
560 initialization name. C<undef> means that passing the value in on instantiation
567 before foo => sub { ... };
569 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
574 around foo => sub { ... };
576 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
581 after foo => sub { ... };
583 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
586 =head1 SUB QUOTE AWARE
588 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
589 giving us a handy, XS-free speed boost. Any option that is L<Sub::Quote>
590 aware can take advantage of this.
592 =head1 INCOMPATIBILITIES WITH MOOSE
594 There is no built in type system. C<isa> is verified with a coderef, if you
595 need complex types, just make a library of coderefs, or better yet, functions
596 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
597 to L<MooseX::Types::Moose> so that you can write
599 has days_to_live => (is => 'ro', isa => Int);
601 and have it work with both; it is hoped that providing only subrefs as an
602 API will encourage the use of other type systems as well, since it's
603 probably the weakest part of Moose design-wise.
605 C<initializer> is not supported in core since the author considers it to be a
606 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
607 C<coerce> are more likely to be able to fulfill your needs.
609 There is no meta object. If you need this level of complexity you wanted
610 L<Moose> - Moo succeeds at being small because it explicitly does not
611 provide a metaprotocol. However, if you load L<Moose>, then
613 Class::MOP::class_of($moo_class_or_role)
615 will return an appropriate metaclass pre-populated by L<Moo>.
617 No support for C<super>, C<override>, C<inner>, or C<augment> - the author
618 considers augment to be a bad idea, and override can be translated:
620 override foo => sub {
627 my ($orig, $self) = (shift, shift);
633 The C<dump> method is not provided by default. The author suggests loading
634 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
635 using C<$obj-E<gt>$::Dwarn()> instead.
637 L</default> only supports coderefs, because doing otherwise is usually a
640 C<lazy_build> is not supported; you are instead encouraged to use the
641 C<is => 'lazy'> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
643 C<auto_deref> is not supported since the author considers it a bad idea.
645 C<documentation> will show up in a L<Moose> metaclass created from your class
646 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
647 is arguably not an incompatibility.
649 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
650 require it, the metaclass inflation for coerce-alone is a trifle insane
651 and if you attempt to subtype the result will almost certainly break.
653 Handling of warnings: when you C<use Moo> we enable FATAL warnings. The nearest
654 similar invocation for L<Moose> would be:
657 use warnings FATAL => "all";
659 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
660 reduce common boilerplate. The set of shortcuts is the same as in the L<Moose>
661 module L<MooseX::AttributeShortcuts> as of its version 0.009+. So if you:
666 The nearest L<Moose> invocation would be:
671 use warnings FATAL => "all";
672 use MooseX::AttributeShortcuts;
674 or, if you're inheriting from a non-Moose class,
679 use MooseX::NonMoose;
680 use warnings FATAL => "all";
681 use MooseX::AttributeShortcuts;
683 Finally, Moose requires you to call
685 __PACKAGE__->meta->make_immutable;
687 at the end of your class to get an inlined (i.e. not horribly slow)
688 constructor. Moo does it automatically the first time ->new is called
693 Users' IRC: #moose on irc.perl.org
695 Development and contribution IRC: #web-simple on irc.perl.org
699 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
703 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
705 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
707 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
709 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
711 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
713 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
715 ajgb - Alex J. G. BurzyĆski (cpan:AJGB) <ajgb@cpan.org>
717 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
719 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
721 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
725 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
730 This library is free software and may be distributed under the same terms