8 our $VERSION = '0.091004'; # 0.91.4
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});
29 $Moo::HandleMoose::MOUSE{$target} = [
30 grep defined, map Mouse::Util::find_meta($_), @_
31 ] if $INC{"Mouse.pm"};
32 $class->_maybe_reset_handlemoose($target);
34 _install_coderef "${target}::with" => "Moo::with" => sub {
36 Moo::Role->apply_roles_to_package($target, $_[0]);
37 $class->_maybe_reset_handlemoose($target);
39 $MAKERS{$target} = {};
40 _install_coderef "${target}::has" => "Moo::has" => sub {
41 my ($name, %spec) = @_;
42 $class->_constructor_maker_for($target)
43 ->register_attribute_specs($name, \%spec);
44 $class->_accessor_maker_for($target)
45 ->generate_method($target, $name, \%spec);
46 $class->_maybe_reset_handlemoose($target);
48 foreach my $type (qw(before after around)) {
49 _install_coderef "${target}::${type}" => "Moo::${type}" => sub {
50 require Class::Method::Modifiers;
51 _install_modifier($target, $type, @_);
56 @{"${target}::ISA"} = do {
57 require Moo::Object; ('Moo::Object');
58 } unless @{"${target}::ISA"};
60 if ($INC{'Moo/HandleMoose.pm'}) {
61 Moo::HandleMoose::inject_fake_metaclass_for($target);
65 sub _maybe_reset_handlemoose {
66 my ($class, $target) = @_;
67 if ($INC{"Moo/HandleMoose.pm"}) {
68 Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
72 sub _accessor_maker_for {
73 my ($class, $target) = @_;
74 return unless $MAKERS{$target};
75 $MAKERS{$target}{accessor} ||= do {
76 my $maker_class = do {
78 if (my $defer_target =
79 (Sub::Defer::defer_info($target->can('new'))||[])->[0]
81 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
82 $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
89 require Method::Generate::Accessor;
90 'Method::Generate::Accessor'
97 sub _constructor_maker_for {
98 my ($class, $target, $select_super) = @_;
99 return unless $MAKERS{$target};
100 $MAKERS{$target}{constructor} ||= do {
101 require Method::Generate::Constructor;
103 my ($moo_constructor, $con);
105 if ($select_super && $MAKERS{$select_super}) {
106 $moo_constructor = 1;
107 $con = $MAKERS{$select_super}{constructor};
109 my $t_new = $target->can('new');
111 if ($t_new == Moo::Object->can('new')) {
112 $moo_constructor = 1;
113 } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
114 my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
116 $moo_constructor = 1;
117 $con = $MAKERS{$pkg}{constructor};
121 $moo_constructor = 1; # no other constructor, make a Moo one
124 ($con ? ref($con) : 'Method::Generate::Constructor')
127 accessor_generator => $class->_accessor_maker_for($target),
128 construction_string => (
130 ? ($con ? $con->construction_string : undef)
131 : ('$class->'.$target.'::SUPER::new(@_)')
133 subconstructor_handler => (
134 ' if ($Moo::MAKERS{$class}) {'."\n"
135 .' '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
136 .' return $class->new(@_)'.";\n"
141 ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
152 Moo - Minimalist Object Orientation (with Moose compatiblity)
163 my $amount = shift || 1;
165 $self->pounds( $self->pounds - $amount );
175 die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
181 isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
188 my $full = Cat::Food->new(
189 taste => 'DELICIOUS.',
190 brand => 'SWEET-TREATZ',
200 This module is an extremely light-weight, high-performance L<Moose> replacement.
201 It also avoids depending on any XS modules to allow simple deployments. The
202 name C<Moo> is based on the idea that it provides almost -but not quite- two
205 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility. See
206 L</INCOMPATIBILITIES> for more details.
208 =head1 WHY MOO EXISTS
210 If you want a full object system with a rich Metaprotocol, L<Moose> is
213 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
214 takes longer to load than most of my Moo based CGI scripts take to run.
216 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
217 you want "as little as possible" - which means "no metaprotocol", which is
220 By Moo 1.0 I intend to have Moo's equivalent of L<Any::Moose> built in -
221 if Moose gets loaded, any Moo class or role will act as a Moose equivalent
224 Hence - Moo exists as its name - Minimal Object Orientation - with a pledge
225 to make it smooth to upgrade to L<Moose> when you need more than minimal
228 =head1 Moo and Moose - NEW, EXPERIMENTAL
230 If L<Moo> detects L<Moose> being loaded, it will automatically register
231 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
232 to use them in L<Moose> code without it ever realising you aren't using
235 Extending a L<Moose> class or consuming a L<Moose::Role> should also work.
237 So should extending a L<Mouse> class or consuming a L<Mouse::Role>.
239 This means that there is no need for anything like L<Any::Moose> for Moo
240 code - Moo and Moose code should simply interoperate without problem. To
241 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
242 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
243 metaclasses like we do.
245 However, these features are new as of 0.91.0 (0.091000) so while serviceable,
246 they are absolutely certain to not be 100% yet; please do report bugs.
248 If you need to disable the metaclass creation, add:
252 to your code before Moose is loaded, but bear in mind that this switch is
253 currently global and turns the mechanism off entirely, so don't put this
254 in library code, only in a top level script as a temporary measure while
255 you send a bug report.
257 =head1 IMPORTED METHODS
261 Foo::Bar->new( attr1 => 3 );
265 Foo::Bar->new({ attr1 => 3 });
270 my ( $class, @args ) = @_;
272 unshift @args, "attr1" if @args % 2 == 1;
279 The default implementation of this method accepts a hash or hash reference of
280 named parameters. If it receives a single argument that isn't a hash reference
283 You can override this method in your class to handle other types of options
284 passed to the constructor.
286 This method should always return a hash reference of named options.
290 Define a C<BUILD> method on your class and the constructor will automatically
291 call the C<BUILD> method from parent down to child after the object has
292 been instantiated. Typically this is used for object validation or possibly
297 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
298 a C<DESTROY> method is created on first object construction which will call
299 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
300 method from child upwards to parents.
302 Note that the C<DESTROY> method is created on first construction of an object
303 of your class in order to not add overhead to classes without C<DEMOLISH>
304 methods; this may prove slightly surprising if you try and define your own.
308 if ($foo->does('Some::Role1')) {
312 Returns true if the object composes in the passed role.
314 =head1 IMPORTED SUBROUTINES
318 extends 'Parent::Class';
320 Declares base class. Multiple superclasses can be passed for multiple
321 inheritance (but please use roles instead).
323 Calling extends more than once will REPLACE your superclasses, not add to
324 them like 'use base' would.
332 with 'Some::Role1', 'Some::Role2';
334 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
335 class. An error will be raised if these roles have conflicting methods.
343 Declares an attribute for the class.
345 The options for C<has> are as follows:
351 B<required>, may be C<ro>, C<rw>, C<lazy> or C<rwp>.
353 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
354 a getter only - by defaulting C<reader> to the name of the attribute.
356 C<rw> generates a normal getter/setter by defauting C<accessor> to the
357 name of the attribute.
359 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
360 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
361 attributes. This feature was my attempt to fix my incompetence when
362 originally designing C<lazy_build>, and is also implemented by
363 L<MooseX::AttributeShortcuts>.
365 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
366 C<_set_${attribute_name}> for attributes that are designed to be written
367 from inside of the class, but read-only from outside.
368 This feature comes from L<MooseX::AttributeShortcuts>.
372 Takes a coderef which is meant to validate the attribute. Unlike L<Moose> Moo
373 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
377 die "$_[0] is not a number!" unless looks_like_number $_[0]
380 L<Sub::Quote aware|/SUB QUOTE AWARE>
382 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
383 subroutine has been supplied, C<isa> checks are not structural to your code
384 and can, if desired, be omitted on non-debug builds (although if this results
385 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
386 nothing except that you get to keep both halves).
388 If you want L<MooseX::Types> style named types, look at
389 L<MooX::Types::MooseLike>.
391 To cause your C<isa> entries to be automatically mapped to named
392 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
393 of creating an anonymous type), set:
395 $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
396 require MooseX::Types::Something;
397 return MooseX::Types::Something::TypeName();
400 Note that this example is purely illustrative; anything that returns a
401 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
402 make L<Moose> happy is fine.
406 Takes a coderef which is meant to coerce the attribute. The basic idea is to
407 do something like the following:
409 coerce => quote_sub q{
410 $_[0] + 1 unless $_[0] % 2
413 Note that L<Moo> will always fire your coercion - this is to permit
414 isa entries to be used purely for bug trapping, whereas coercions are
415 always structural to your code. We do, however, apply any supplied C<isa>
416 check after the coercion has run to ensure that it returned a valid value.
418 L<Sub::Quote aware|/SUB QUOTE AWARE>
424 handles => 'RobotRole'
426 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
427 becomes the list of methods to handle.
429 Takes a list of methods
431 handles => [ qw( one two ) ]
441 Takes a coderef which will get called any time the attribute is set. This
442 includes the constructor. Coderef will be invoked against the object with the
443 new value as an argument.
445 If you set this to just C<1>, it generates a trigger which calls the
446 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
447 L<MooseX::AttributeShortcuts>.
449 Note that Moose also passes the old value, if any; this feature is not yet
452 L<Sub::Quote aware|/SUB QUOTE AWARE>
456 Takes a coderef which will get called with $self as its only argument
457 to populate an attribute if no value is supplied to the constructor - or
458 if the attribute is lazy, when the attribute is first retrieved if no
459 value has yet been provided.
461 Note that if your default is fired during new() there is no guarantee that
462 other attributes have been populated yet so you should not rely on their
465 L<Sub::Quote aware|/SUB QUOTE AWARE>
469 Takes a method name which will return true if an attribute has a value.
471 If you set this to just C<1>, the predicate is automatically named
472 C<has_${attr_name}> if your attribute's name does not start with an
473 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
474 This feature comes from L<MooseX::AttributeShortcuts>.
478 Takes a method name which will be called to create the attribute - functions
479 exactly like default except that instead of calling
487 If you set this to just C<1>, the predicate is automatically named
488 C<_build_${attr_name}>. This feature comes from L<MooseX::AttributeShortcuts>.
492 Takes a method name which will clear the attribute.
494 If you set this to just C<1>, the clearer is automatically named
495 C<clear_${attr_name}> if your attribute's name does not start with an
496 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
497 This feature comes from L<MooseX::AttributeShortcuts>.
501 B<Boolean>. Set this if you want values for the attribute to be grabbed
502 lazily. This is usually a good idea if you have a L</builder> which requires
503 another attribute to be set.
507 B<Boolean>. Set this if the attribute must be passed on instantiation.
511 The value of this attribute will be the name of the method to get the value of
512 the attribute. If you like Java style methods, you might set this to
517 The value of this attribute will be the name of the method to set the value of
518 the attribute. If you like Java style methods, you might set this to
523 B<Boolean>. Set this if you want the reference that the attribute contains to
524 be weakened; use this when circular references are possible, which will cause
529 Takes the name of the key to look for at instantiation time of the object. A
530 common use of this is to make an underscored attribute have a non-underscored
531 initialization name. C<undef> means that passing the value in on instantiation
538 before foo => sub { ... };
540 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
545 around foo => sub { ... };
547 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
552 after foo => sub { ... };
554 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
557 =head1 SUB QUOTE AWARE
559 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
560 giving us a handy, XS-free speed boost. Any option that is L<Sub::Quote>
561 aware can take advantage of this.
563 =head1 INCOMPATIBILITIES WITH MOOSE
565 There is no built in type system. C<isa> is verified with a coderef, if you
566 need complex types, just make a library of coderefs, or better yet, functions
567 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
568 to L<MooseX::Types::Moose> so that you can write
570 has days_to_live => (is => 'ro', isa => Int);
572 and have it work with both; it is hoped that providing only subrefs as an
573 API will encourage the use of other type systems as well, since it's
574 probably the weakest part of Moose design-wise.
576 C<initializer> is not supported in core since the author considers it to be a
577 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
578 C<coerce> are more likely to be able to fulfill your needs.
580 There is no meta object. If you need this level of complexity you wanted
581 L<Moose> - Moo succeeds at being small because it explicitly does not
582 provide a metaprotocol. However, if you load L<Moose>, then
584 Class::MOP::class_of($moo_class_or_role)
586 will return an appropriate metaclass pre-populated by L<Moo>.
588 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
589 be handled by around albeit with a little more typing, and the author considers
590 augment to be a bad idea.
592 The C<dump> method is not provided by default. The author suggests loading
593 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
594 using C<$obj-E<gt>$::Dwarn()> instead.
596 L</default> only supports coderefs, because doing otherwise is usually a
599 C<lazy_build> is not supported; you are instead encouraged to use the
600 C<is => 'lazy'> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
602 C<auto_deref> is not supported since the author considers it a bad idea.
604 C<documentation> will show up in a L<Moose> metaclass created from your class
605 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
606 is arguably not an incompatibility.
608 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
609 require it, the metaclass inflation for coerce-alone is a trifle insane
610 and if you attempt to subtype the result will almost certainly break.
612 Handling of warnings: when you C<use Moo> we enable FATAL warnings. The nearest
613 similar invocation for L<Moose> would be:
616 use warnings FATAL => "all";
618 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
619 reduce common boilerplate. The set of shortcuts is the same as in the L<Moose>
620 module L<MooseX::AttributeShortcuts> as of its version 0.009+. So if you:
625 The nearest L<Moose> invocation would be:
630 use warnings FATAL => "all";
631 use MooseX::AttributeShortcuts;
633 or, if you're inheriting from a non-Moose class,
638 use MooseX::NonMoose;
639 use warnings FATAL => "all";
640 use MooseX::AttributeShortcuts;
642 Finally, Moose requires you to call
644 __PACKAGE__->meta->make_immutable;
646 at the end of your class to get an inlined (i.e. not horribly slow)
647 constructor. Moo does it automatically the first time ->new is called
652 IRC: #web-simple on irc.perl.org
656 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
660 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
662 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
664 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
666 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
668 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
670 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
672 ajgb - Alex J. G. BurzyĆski (cpan:AJGB) <ajgb@cpan.org>
674 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
676 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
680 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
685 This library is free software and may be distributed under the same terms