cafeed77584c851462203b1ffb8d3b0c5549d56f
[gitmo/Moo.git] / lib / Moo.pm
1 package Moo;
2
3 use strictures 1;
4 use Moo::_Utils;
5 use B 'perlstring';
6 use Sub::Defer ();
7
8 our $VERSION = '1.003000';
9 $VERSION = eval $VERSION;
10
11 require Moo::sification;
12
13 our %MAKERS;
14
15 sub _install_tracked {
16   my ($target, $name, $code) = @_;
17   $MAKERS{$target}{exports}{$name} = $code;
18   _install_coderef "${target}::${name}" => "Moo::${name}" => $code;
19 }
20
21 sub import {
22   my $target = caller;
23   my $class = shift;
24   strictures->import;
25   if ($Role::Tiny::INFO{$target} and $Role::Tiny::INFO{$target}{is_role}) {
26     die "Cannot import Moo into a role";
27   }
28   $MAKERS{$target} ||= {};
29   _install_tracked $target => extends => sub {
30     $class->_set_superclasses($target, @_);
31     $class->_maybe_reset_handlemoose($target);
32     return;
33   };
34   _install_tracked $target => with => sub {
35     require Moo::Role;
36     Moo::Role->apply_roles_to_package($target, @_);
37     $class->_maybe_reset_handlemoose($target);
38   };
39   _install_tracked $target => has => sub {
40     my $name_proto = shift;
41     my @name_proto = ref $name_proto eq 'ARRAY' ? @$name_proto : $name_proto;
42     if (@_ % 2 != 0) {
43       require Carp;
44       Carp::croak("Invalid options for " . join(', ', map "'$_'", @name_proto)
45         . " attribute(s): even number of arguments expected, got " . scalar @_)
46     }
47     my %spec = @_;
48     foreach my $name (@name_proto) {
49       # Note that when multiple attributes specified, each attribute
50       # needs a separate \%specs hashref
51       my $spec_ref = @name_proto > 1 ? +{%spec} : \%spec;
52       $class->_constructor_maker_for($target)
53             ->register_attribute_specs($name, $spec_ref);
54       $class->_accessor_maker_for($target)
55             ->generate_method($target, $name, $spec_ref);
56       $class->_maybe_reset_handlemoose($target);
57     }
58     return;
59   };
60   foreach my $type (qw(before after around)) {
61     _install_tracked $target => $type => sub {
62       require Class::Method::Modifiers;
63       _install_modifier($target, $type, @_);
64       return;
65     };
66   }
67   return if $MAKERS{$target}{is_class}; # already exported into this package
68   $MAKERS{$target}{is_class} = 1;
69   {
70     no strict 'refs';
71     @{"${target}::ISA"} = do {
72       require Moo::Object; ('Moo::Object');
73     } unless @{"${target}::ISA"};
74   }
75   if ($INC{'Moo/HandleMoose.pm'}) {
76     Moo::HandleMoose::inject_fake_metaclass_for($target);
77   }
78 }
79
80 sub unimport {
81   my $target = caller;
82   _unimport_coderefs($target, $MAKERS{$target});
83 }
84
85 sub _set_superclasses {
86   my $class = shift;
87   my $target = shift;
88   foreach my $superclass (@_) {
89     _load_module($superclass);
90     if ($INC{"Role/Tiny.pm"} && $Role::Tiny::INFO{$superclass}) {
91       require Carp;
92       Carp::croak("Can't extend role '$superclass'");
93     }
94   }
95   # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
96   @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
97   if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
98     delete _getstash($target)->{new};
99     Moo->_constructor_maker_for($target)
100        ->register_attribute_specs(%{$old->all_attribute_specs});
101   }
102   elsif (!$target->isa('Moo::Object')) {
103     Moo->_constructor_maker_for($target);
104   }
105   no warnings 'once'; # piss off. -- mst
106   $Moo::HandleMoose::MOUSE{$target} = [
107     grep defined, map Mouse::Util::find_meta($_), @_
108   ] if Mouse::Util->can('find_meta');
109 }
110
111 sub _maybe_reset_handlemoose {
112   my ($class, $target) = @_;
113   if ($INC{"Moo/HandleMoose.pm"}) {
114     Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
115   }
116 }
117
118 sub _accessor_maker_for {
119   my ($class, $target) = @_;
120   return unless $MAKERS{$target};
121   $MAKERS{$target}{accessor} ||= do {
122     my $maker_class = do {
123       if (my $m = do {
124             if (my $defer_target = 
125                   (Sub::Defer::defer_info($target->can('new'))||[])->[0]
126               ) {
127               my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
128               $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
129             } else {
130               undef;
131             }
132           }) {
133         ref($m);
134       } else {
135         require Method::Generate::Accessor;
136         'Method::Generate::Accessor'
137       }
138     };
139     $maker_class->new;
140   }
141 }
142
143 sub _constructor_maker_for {
144   my ($class, $target) = @_;
145   return unless $MAKERS{$target};
146   $MAKERS{$target}{constructor} ||= do {
147     require Method::Generate::Constructor;
148     require Sub::Defer;
149     my ($moo_constructor, $con);
150
151     my $t_new = $target->can('new');
152     if ($t_new) {
153       if ($t_new == Moo::Object->can('new')) {
154         $moo_constructor = 1;
155       } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
156         my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
157         if ($MAKERS{$pkg}) {
158           $moo_constructor = 1;
159           $con = $MAKERS{$pkg}{constructor};
160         }
161       }
162     } else {
163       $moo_constructor = 1; # no other constructor, make a Moo one
164     }
165     ($con ? ref($con) : 'Method::Generate::Constructor')
166       ->new(
167         package => $target,
168         accessor_generator => $class->_accessor_maker_for($target),
169         construction_string => (
170           $moo_constructor
171             ? ($con ? $con->construction_string : undef)
172             : ('$class->'.$target.'::SUPER::new($class->can(q[FOREIGNBUILDARGS]) ? $class->FOREIGNBUILDARGS(@_) : @_)')
173         ),
174         subconstructor_handler => (
175           '      if ($Moo::MAKERS{$class}) {'."\n"
176           .'        '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
177           .'        return $class->new(@_)'.";\n"
178           .'      } elsif ($INC{"Moose.pm"} and my $meta = Class::MOP::get_metaclass_by_name($class)) {'."\n"
179           .'        return $meta->new_object($class->BUILDARGS(@_));'."\n"
180           .'      }'."\n"
181         ),
182       )
183       ->install_delayed
184       ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
185   }
186 }
187
188 1;
189 =pod
190
191 =encoding utf-8
192
193 =head1 NAME
194
195 Moo - Minimalist Object Orientation (with Moose compatibility)
196
197 =head1 SYNOPSIS
198
199  package Cat::Food;
200
201  use Moo;
202
203  sub feed_lion {
204    my $self = shift;
205    my $amount = shift || 1;
206
207    $self->pounds( $self->pounds - $amount );
208  }
209
210  has taste => (
211    is => 'ro',
212  );
213
214  has brand => (
215    is  => 'ro',
216    isa => sub {
217      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
218    },
219  );
220
221  has pounds => (
222    is  => 'rw',
223    isa => sub { die "$_[0] is too much cat food!" unless $_[0] < 15 },
224  );
225
226  1;
227
228 And elsewhere:
229
230  my $full = Cat::Food->new(
231     taste  => 'DELICIOUS.',
232     brand  => 'SWEET-TREATZ',
233     pounds => 10,
234  );
235
236  $full->feed_lion;
237
238  say $full->pounds;
239
240 =head1 DESCRIPTION
241
242 This module is an extremely light-weight subset of L<Moose> optimised for
243 rapid startup and "pay only for what you use".
244
245 It also avoids depending on any XS modules to allow simple deployments.  The
246 name C<Moo> is based on the idea that it provides almost -- but not quite -- two
247 thirds of L<Moose>.
248
249 Unlike L<Mouse> this module does not aim at full compatibility with
250 L<Moose>'s surface syntax, preferring instead of provide full interoperability
251 via the metaclass inflation capabilities described in L</MOO AND MOOSE>.
252
253 For a full list of the minor differences between L<Moose> and L<Moo>'s surface
254 syntax, see L</INCOMPATIBILITIES WITH MOOSE>.
255
256 =head1 WHY MOO EXISTS
257
258 If you want a full object system with a rich Metaprotocol, L<Moose> is
259 already wonderful.
260
261 However, sometimes you're writing a command line script or a CGI script
262 where fast startup is essential, or code designed to be deployed as a single
263 file via L<App::FatPacker>, or you're writing a CPAN module and you want it
264 to be usable by people with those constraints.
265
266 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
267 takes longer to load than most of my Moo based CGI scripts take to run.
268
269 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
270 you want "as little as possible" -- which means "no metaprotocol", which is
271 what Moo provides.
272
273 Better still, if you install and load L<Moose>, we set up metaclasses for your
274 L<Moo> classes and L<Moo::Role> roles, so you can use them in L<Moose> code
275 without ever noticing that some of your codebase is using L<Moo>.
276
277 Hence, Moo exists as its name -- Minimal Object Orientation -- with a pledge
278 to make it smooth to upgrade to L<Moose> when you need more than minimal
279 features.
280
281 =head1 MOO AND MOOSE
282
283 If L<Moo> detects L<Moose> being loaded, it will automatically register
284 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
285 to use them in L<Moose> code without anybody ever noticing you aren't using
286 L<Moose> everywhere.
287
288 L<Moo> will also create L<Moose type constraints|Moose::Manual::Types> for
289 classes and roles, so that C<< isa => 'MyClass' >> and C<< isa => 'MyRole' >>
290 work the same as for L<Moose> classes and roles.
291
292 Extending a L<Moose> class or consuming a L<Moose::Role> will also work.
293
294 So will extending a L<Mouse> class or consuming a L<Mouse::Role> - but note
295 that we don't provide L<Mouse> metaclasses or metaroles so the other way
296 around doesn't work. This feature exists for L<Any::Moose> users porting to
297 L<Moo>; enabling L<Mouse> users to use L<Moo> classes is not a priority for us.
298
299 This means that there is no need for anything like L<Any::Moose> for Moo
300 code - Moo and Moose code should simply interoperate without problem. To
301 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
302 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
303 metaclasses like L<Moo> does.
304
305 If you want types to be upgraded to the L<Moose> types, use
306 L<MooX::Types::MooseLike> and install the L<MooseX::Types> library to
307 match the L<MooX::Types::MooseLike> library you're using - L<Moo> will
308 load the L<MooseX::Types> library and use that type for the newly created
309 metaclass.
310
311 If you need to disable the metaclass creation, add:
312
313   no Moo::sification;
314
315 to your code before Moose is loaded, but bear in mind that this switch is
316 currently global and turns the mechanism off entirely so don't put this
317 in library code.
318
319 =head1 MOO AND CLASS::XSACCESSOR
320
321 If a new enough version of L<Class::XSAccessor> is available, it
322 will be used to generate simple accessors, readers, and writers for
323 a speed boost.  Simple accessors are those without lazy defaults,
324 type checks/coercions, or triggers.  Readers and writers generated
325 by L<Class::XSAccessor> will behave slightly differently: they will
326 reject attempts to call them with the incorrect number of parameters.
327
328 =head1 MOO VERSUS ANY::MOOSE
329
330 L<Any::Moose> will load L<Mouse> normally, and L<Moose> in a program using
331 L<Moose> - which theoretically allows you to get the startup time of L<Mouse>
332 without disadvantaging L<Moose> users.
333
334 Sadly, this doesn't entirely work, since the selection is load order dependent
335 - L<Moo>'s metaclass inflation system explained above in L</MOO AND MOOSE> is
336 significantly more reliable.
337
338 So if you want to write a CPAN module that loads fast or has only pure perl
339 dependencies but is also fully usable by L<Moose> users, you should be using
340 L<Moo>.
341
342 For a full explanation, see the article
343 L<http://shadow.cat/blog/matt-s-trout/moo-versus-any-moose> which explains
344 the differing strategies in more detail and provides a direct example of
345 where L<Moo> succeeds and L<Any::Moose> fails.
346
347 =head1 IMPORTED METHODS
348
349 =head2 new
350
351  Foo::Bar->new( attr1 => 3 );
352
353 or
354
355  Foo::Bar->new({ attr1 => 3 });
356
357 =head2 BUILDARGS
358
359  sub BUILDARGS {
360    my ( $class, @args ) = @_;
361
362    unshift @args, "attr1" if @args % 2 == 1;
363
364    return { @args };
365  };
366
367  Foo::Bar->new( 3 );
368
369 The default implementation of this method accepts a hash or hash reference of
370 named parameters. If it receives a single argument that isn't a hash reference
371 it throws an error.
372
373 You can override this method in your class to handle other types of options
374 passed to the constructor.
375
376 This method should always return a hash reference of named options.
377
378 =head2 FOREIGNBUILDARGS
379
380 If you are inheriting from a non-Moo class, the arguments passed to the parent
381 class constructor can be manipulated by defining a C<FOREIGNBUILDARGS> method.
382 It will receive the same arguments as C<BUILDARGS>, and should return a list
383 of arguments to pass to the parent class constructor.
384
385 =head2 BUILD
386
387 Define a C<BUILD> method on your class and the constructor will automatically
388 call the C<BUILD> method from parent down to child after the object has
389 been instantiated.  Typically this is used for object validation or possibly
390 logging.
391
392 =head2 DEMOLISH
393
394 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
395 a C<DESTROY> method is created on first object construction which will call
396 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
397 method from child upwards to parents.
398
399 Note that the C<DESTROY> method is created on first construction of an object
400 of your class in order to not add overhead to classes without C<DEMOLISH>
401 methods; this may prove slightly surprising if you try and define your own.
402
403 =head2 does
404
405  if ($foo->does('Some::Role1')) {
406    ...
407  }
408
409 Returns true if the object composes in the passed role.
410
411 =head1 IMPORTED SUBROUTINES
412
413 =head2 extends
414
415  extends 'Parent::Class';
416
417 Declares base class. Multiple superclasses can be passed for multiple
418 inheritance (but please use roles instead).
419
420 Calling extends more than once will REPLACE your superclasses, not add to
421 them like 'use base' would.
422
423 =head2 with
424
425  with 'Some::Role1';
426
427 or
428
429  with 'Some::Role1', 'Some::Role2';
430
431 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
432 class.  An error will be raised if these roles have conflicting methods.
433
434 =head2 has
435
436  has attr => (
437    is => 'ro',
438  );
439
440 Declares an attribute for the class.
441
442  package Foo;
443  use Moo;
444  has 'attr' => (
445    is => 'ro'
446  );
447
448  package Bar;
449  use Moo;
450  extends 'Foo';
451  has '+attr' => (
452    default => sub { "blah" },
453  );
454
455 Using the C<+> notation, it's possible to override an attribute.
456
457 The options for C<has> are as follows:
458
459 =over 2
460
461 =item * is
462
463 B<required>, may be C<ro>, C<lazy>, C<rwp> or C<rw>.
464
465 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
466 a getter only - by defaulting C<reader> to the name of the attribute.
467
468 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
469 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
470 attributes.  This feature was my attempt to fix my incompetence when
471 originally designing C<lazy_build>, and is also implemented by
472 L<MooseX::AttributeShortcuts>. There is, however, nothing to stop you
473 using C<lazy> and C<builder> yourself with C<rwp> or C<rw> - it's just that
474 this isn't generally a good idea so we don't provide a shortcut for it.
475
476 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
477 C<_set_${attribute_name}> for attributes that are designed to be written
478 from inside of the class, but read-only from outside.
479 This feature comes from L<MooseX::AttributeShortcuts>.
480
481 C<rw> generates a normal getter/setter by defaulting C<accessor> to the
482 name of the attribute.
483
484 =item * isa
485
486 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose>, Moo
487 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
488 one should do
489
490  isa => sub {
491    die "$_[0] is not a number!" unless looks_like_number $_[0]
492  },
493
494 Note that the return value is ignored, only whether the sub lives or
495 dies matters.
496
497 L<Sub::Quote aware|/SUB QUOTE AWARE>
498
499 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
500 subroutine has been supplied, C<isa> checks are not structural to your code
501 and can, if desired, be omitted on non-debug builds (although if this results
502 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
503 nothing except that you get to keep both halves).
504
505 If you want L<MooseX::Types> style named types, look at
506 L<MooX::Types::MooseLike>.
507
508 To cause your C<isa> entries to be automatically mapped to named
509 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
510 of creating an anonymous type), set:
511
512   $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
513     require MooseX::Types::Something;
514     return MooseX::Types::Something::TypeName();
515   };
516
517 Note that this example is purely illustrative; anything that returns a
518 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
519 make L<Moose> happy is fine.
520
521 =item * coerce
522
523 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
524 do something like the following:
525
526  coerce => sub {
527    $_[0] + 1 unless $_[0] % 2
528  },
529
530 Note that L<Moo> will always fire your coercion: this is to permit
531 C<isa> entries to be used purely for bug trapping, whereas coercions are
532 always structural to your code. We do, however, apply any supplied C<isa>
533 check after the coercion has run to ensure that it returned a valid value.
534
535 L<Sub::Quote aware|/SUB QUOTE AWARE>
536
537 =item * handles
538
539 Takes a string
540
541   handles => 'RobotRole'
542
543 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
544 becomes the list of methods to handle.
545
546 Takes a list of methods
547
548  handles => [ qw( one two ) ]
549
550 Takes a hashref
551
552  handles => {
553    un => 'one',
554  }
555
556 =item * C<trigger>
557
558 Takes a coderef which will get called any time the attribute is set. This
559 includes the constructor, but not default or built values. Coderef will be
560 invoked against the object with the new value as an argument.
561
562 If you set this to just C<1>, it generates a trigger which calls the
563 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
564 L<MooseX::AttributeShortcuts>.
565
566 Note that Moose also passes the old value, if any; this feature is not yet
567 supported.
568
569 L<Sub::Quote aware|/SUB QUOTE AWARE>
570
571 =item * C<default>
572
573 Takes a coderef which will get called with $self as its only argument
574 to populate an attribute if no value is supplied to the constructor - or
575 if the attribute is lazy, when the attribute is first retrieved if no
576 value has yet been provided.
577
578 If a simple scalar is provided, it will be inlined as a string. Any non-code
579 reference (hash, array) will result in an error - for that case instead use
580 a code reference that returns the desired value.
581
582 Note that if your default is fired during new() there is no guarantee that
583 other attributes have been populated yet so you should not rely on their
584 existence.
585
586 L<Sub::Quote aware|/SUB QUOTE AWARE>
587
588 =item * C<predicate>
589
590 Takes a method name which will return true if an attribute has a value.
591
592 If you set this to just C<1>, the predicate is automatically named
593 C<has_${attr_name}> if your attribute's name does not start with an
594 underscore, or C<_has_${attr_name_without_the_underscore}> if it does.
595 This feature comes from L<MooseX::AttributeShortcuts>.
596
597 =item * C<builder>
598
599 Takes a method name which will be called to create the attribute - functions
600 exactly like default except that instead of calling
601
602   $default->($self);
603
604 Moo will call
605
606   $self->$builder;
607
608 The following features come from L<MooseX::AttributeShortcuts>:
609
610 If you set this to just C<1>, the builder is automatically named
611 C<_build_${attr_name}>.
612
613 If you set this to a coderef or code-convertible object, that variable will be
614 installed under C<$class::_build_${attr_name}> and the builder set to the same
615 name.
616
617 =item * C<clearer>
618
619 Takes a method name which will clear the attribute.
620
621 If you set this to just C<1>, the clearer is automatically named
622 C<clear_${attr_name}> if your attribute's name does not start with an
623 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
624 This feature comes from L<MooseX::AttributeShortcuts>.
625
626 =item * C<lazy>
627
628 B<Boolean>.  Set this if you want values for the attribute to be grabbed
629 lazily.  This is usually a good idea if you have a L</builder> which requires
630 another attribute to be set.
631
632 =item * C<required>
633
634 B<Boolean>.  Set this if the attribute must be passed on instantiation.
635
636 =item * C<reader>
637
638 The value of this attribute will be the name of the method to get the value of
639 the attribute.  If you like Java style methods, you might set this to
640 C<get_foo>
641
642 =item * C<writer>
643
644 The value of this attribute will be the name of the method to set the value of
645 the attribute.  If you like Java style methods, you might set this to
646 C<set_foo>.
647
648 =item * C<weak_ref>
649
650 B<Boolean>.  Set this if you want the reference that the attribute contains to
651 be weakened; use this when circular references are possible, which will cause
652 leaks.
653
654 =item * C<init_arg>
655
656 Takes the name of the key to look for at instantiation time of the object.  A
657 common use of this is to make an underscored attribute have a non-underscored
658 initialization name. C<undef> means that passing the value in on instantiation
659 is ignored.
660
661 =item * C<moosify>
662
663 Takes either a coderef or array of coderefs which is meant to transform the
664 given attributes specifications if necessary when upgrading to a Moose role or
665 class. You shouldn't need this by default, but is provided as a means of
666 possible extensibility.
667
668 =back
669
670 =head2 before
671
672  before foo => sub { ... };
673
674 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
675 documentation.
676
677 =head2 around
678
679  around foo => sub { ... };
680
681 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
682 documentation.
683
684 =head2 after
685
686  after foo => sub { ... };
687
688 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
689 documentation.
690
691 =head1 SUB QUOTE AWARE
692
693 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
694 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
695 aware can take advantage of this.
696
697 To do this, you can write
698
699   use Moo;
700   use Sub::Quote;
701
702   has foo => (
703     is => 'ro',
704     isa => quote_sub(q{ die "Not <3" unless $_[0] < 3 })
705   );
706
707 which will be inlined as
708
709   do {
710     local @_ = ($_[0]->{foo});
711     die "Not <3" unless $_[0] < 3;
712   }
713
714 or to avoid localizing @_,
715
716   has foo => (
717     is => 'ro',
718     isa => quote_sub(q{ my ($val) = @_; die "Not <3" unless $val < 3 })
719   );
720
721 which will be inlined as
722
723   do {
724     my ($val) = ($_[0]->{foo});
725     die "Not <3" unless $val < 3;
726   }
727
728 See L<Sub::Quote> for more information, including how to pass lexical
729 captures that will also be compiled into the subroutine.
730
731 =head1 INCOMPATIBILITIES WITH MOOSE
732
733 There is no built-in type system.  C<isa> is verified with a coderef; if you
734 need complex types, just make a library of coderefs, or better yet, functions
735 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
736 to L<MooseX::Types::Moose> so that you can write
737
738   has days_to_live => (is => 'ro', isa => Int);
739
740 and have it work with both; it is hoped that providing only subrefs as an
741 API will encourage the use of other type systems as well, since it's
742 probably the weakest part of Moose design-wise.
743
744 C<initializer> is not supported in core since the author considers it to be a
745 bad idea and Moose best practices recommend avoiding it. Meanwhile C<trigger> or
746 C<coerce> are more likely to be able to fulfill your needs.
747
748 There is no meta object.  If you need this level of complexity you wanted
749 L<Moose> - Moo succeeds at being small because it explicitly does not
750 provide a metaprotocol. However, if you load L<Moose>, then
751
752   Class::MOP::class_of($moo_class_or_role)
753
754 will return an appropriate metaclass pre-populated by L<Moo>.
755
756 No support for C<super>, C<override>, C<inner>, or C<augment> - the author
757 considers augment to be a bad idea, and override can be translated:
758
759   override foo => sub {
760     ...
761     super();
762     ...
763   };
764
765   around foo => sub {
766     my ($orig, $self) = (shift, shift);
767     ...
768     $self->$orig(@_);
769     ...
770   };
771
772 The C<dump> method is not provided by default. The author suggests loading
773 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
774 using C<$obj-E<gt>$::Dwarn()> instead.
775
776 L</default> only supports coderefs and plain scalars, because passing a hash
777 or array reference as a default is almost always incorrect since the value is
778 then shared between all objects using that default.
779
780 C<lazy_build> is not supported; you are instead encouraged to use the
781 C<< is => 'lazy' >> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
782
783 C<auto_deref> is not supported since the author considers it a bad idea and
784 it has been considered best practice to avoid it for some time.
785
786 C<documentation> will show up in a L<Moose> metaclass created from your class
787 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
788 is arguably not an incompatibility.
789
790 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
791 require it, the metaclass inflation for coerce alone is a trifle insane
792 and if you attempt to subtype the result will almost certainly break.
793
794 Handling of warnings: when you C<use Moo> we enable FATAL warnings.  The nearest
795 similar invocation for L<Moose> would be:
796
797   use Moose;
798   use warnings FATAL => "all";
799
800 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
801 reduce common boilerplate.  The set of shortcuts is the same as in the L<Moose>
802 module L<MooseX::AttributeShortcuts> as of its version 0.009+.  So if you:
803
804     package MyClass;
805     use Moo;
806
807 The nearest L<Moose> invocation would be:
808
809     package MyClass;
810
811     use Moose;
812     use warnings FATAL => "all";
813     use MooseX::AttributeShortcuts;
814
815 or, if you're inheriting from a non-Moose class,
816
817     package MyClass;
818
819     use Moose;
820     use MooseX::NonMoose;
821     use warnings FATAL => "all";
822     use MooseX::AttributeShortcuts;
823
824 Finally, Moose requires you to call
825
826     __PACKAGE__->meta->make_immutable;
827
828 at the end of your class to get an inlined (i.e. not horribly slow)
829 constructor. Moo does it automatically the first time ->new is called
830 on your class. (C<make_immutable> is a no-op in Moo to ease migration.)
831
832 An extension L<MooX::late> exists to ease translating Moose packages
833 to Moo by providing a more Moose-like interface.
834
835 =head1 SUPPORT
836
837 Users' IRC: #moose on irc.perl.org
838
839 =for html <a href="http://chat.mibbit.com/#moose@irc.perl.org">(click for instant chatroom login)</a>
840
841 Development and contribution IRC: #web-simple on irc.perl.org
842
843 =for html <a href="http://chat.mibbit.com/#web-simple@irc.perl.org">(click for instant chatroom login)</a>
844
845 Bugtracker: L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Moo>
846
847 Git repository: L<git://git.shadowcat.co.uk/gitmo/Moo.git>
848
849 Git web access: L<http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=gitmo/Moo.git>
850
851 =head1 AUTHOR
852
853 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
854
855 =head1 CONTRIBUTORS
856
857 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
858
859 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
860
861 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
862
863 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
864
865 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
866
867 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
868
869 ajgb - Alex J. G. Burzyński (cpan:AJGB) <ajgb@cpan.org>
870
871 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
872
873 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
874
875 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
876
877 ilmari - Dagfinn Ilmari Mannsåker (cpan:ILMARI) <ilmari@ilmari.org>
878
879 tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
880
881 haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
882
883 mattp - Matt Phillips (cpan:MATTP) <mattp@cpan.org>
884
885 =head1 COPYRIGHT
886
887 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
888 as listed above.
889
890 =head1 LICENSE
891
892 This library is free software and may be distributed under the same terms
893 as perl itself. See L<http://dev.perl.org/licenses/>.
894
895 =cut