don't assume Scalar::Util is imported into the current package
[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 = '0.091010'; # 0.91.10
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   return if $MAKERS{$target}; # already exported into this package
26   $MAKERS{$target} = {};
27   _install_tracked $target => extends => sub {
28     _load_module($_) for @_;
29     # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
30     @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
31     if (my $old = delete $Moo::MAKERS{$target}{constructor}) {
32       delete _getstash($target)->{new};
33       Moo->_constructor_maker_for($target)
34          ->register_attribute_specs(%{$old->all_attribute_specs});
35     }
36     no warnings 'once'; # piss off. -- mst
37     $Moo::HandleMoose::MOUSE{$target} = [
38       grep defined, map Mouse::Util::find_meta($_), @_
39     ] if $INC{"Mouse.pm"};
40     $class->_maybe_reset_handlemoose($target);
41     return;
42   };
43   _install_tracked $target => with => sub {
44     require Moo::Role;
45     Moo::Role->apply_roles_to_package($target, @_);
46     $class->_maybe_reset_handlemoose($target);
47   };
48   _install_tracked $target => has => sub {
49     my ($name, %spec) = @_;
50     $class->_constructor_maker_for($target)
51           ->register_attribute_specs($name, \%spec);
52     $class->_accessor_maker_for($target)
53           ->generate_method($target, $name, \%spec);
54     $class->_maybe_reset_handlemoose($target);
55     return;
56   };
57   foreach my $type (qw(before after around)) {
58     _install_tracked $target => $type => sub {
59       require Class::Method::Modifiers;
60       _install_modifier($target, $type, @_);
61       return;
62     };
63   }
64   {
65     no strict 'refs';
66     @{"${target}::ISA"} = do {
67       require Moo::Object; ('Moo::Object');
68     } unless @{"${target}::ISA"};
69   }
70   if ($INC{'Moo/HandleMoose.pm'}) {
71     Moo::HandleMoose::inject_fake_metaclass_for($target);
72   }
73 }
74
75 sub unimport {
76   my $target = caller;
77   _unimport_coderefs($target, $MAKERS{$target});
78 }
79
80 sub _maybe_reset_handlemoose {
81   my ($class, $target) = @_;
82   if ($INC{"Moo/HandleMoose.pm"}) {
83     Moo::HandleMoose::maybe_reinject_fake_metaclass_for($target);
84   }
85 }
86
87 sub _accessor_maker_for {
88   my ($class, $target) = @_;
89   return unless $MAKERS{$target};
90   $MAKERS{$target}{accessor} ||= do {
91     my $maker_class = do {
92       if (my $m = do {
93             if (my $defer_target = 
94                   (Sub::Defer::defer_info($target->can('new'))||[])->[0]
95               ) {
96               my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
97               $MAKERS{$pkg} && $MAKERS{$pkg}{accessor};
98             } else {
99               undef;
100             }
101           }) {
102         ref($m);
103       } else {
104         require Method::Generate::Accessor;
105         'Method::Generate::Accessor'
106       }
107     };
108     $maker_class->new;
109   }
110 }
111
112 sub _constructor_maker_for {
113   my ($class, $target, $select_super) = @_;
114   return unless $MAKERS{$target};
115   $MAKERS{$target}{constructor} ||= do {
116     require Method::Generate::Constructor;
117     require Sub::Defer;
118     my ($moo_constructor, $con);
119
120     if ($select_super && $MAKERS{$select_super}) {
121       $moo_constructor = 1;
122       $con = $MAKERS{$select_super}{constructor};
123     } else {
124       my $t_new = $target->can('new');
125       if ($t_new) {
126         if ($t_new == Moo::Object->can('new')) {
127           $moo_constructor = 1;
128         } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
129           my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
130           if ($MAKERS{$pkg}) {
131             $moo_constructor = 1;
132             $con = $MAKERS{$pkg}{constructor};
133           }
134         }
135       } else {
136         $moo_constructor = 1; # no other constructor, make a Moo one
137       }
138     };
139     ($con ? ref($con) : 'Method::Generate::Constructor')
140       ->new(
141         package => $target,
142         accessor_generator => $class->_accessor_maker_for($target),
143         construction_string => (
144           $moo_constructor
145             ? ($con ? $con->construction_string : undef)
146             : ('$class->'.$target.'::SUPER::new(@_)')
147         ),
148         subconstructor_handler => (
149           '      if ($Moo::MAKERS{$class}) {'."\n"
150           .'        '.$class.'->_constructor_maker_for($class,'.perlstring($target).');'."\n"
151           .'        return $class->new(@_)'.";\n"
152           .'      } elsif ($INC{"Moose.pm"} and my $meta = Class::MOP::get_metaclass_by_name($class)) {'."\n"
153           .'        return $meta->new_object(@_);'."\n"
154           .'      }'."\n"
155         ),
156       )
157       ->install_delayed
158       ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
159   }
160 }
161
162 1;
163 =pod
164
165 =encoding utf-8
166
167 =head1 NAME
168
169 Moo - Minimalist Object Orientation (with Moose compatiblity)
170
171 =head1 SYNOPSIS
172
173  package Cat::Food;
174
175  use Moo;
176  use Sub::Quote;
177
178  sub feed_lion {
179    my $self = shift;
180    my $amount = shift || 1;
181
182    $self->pounds( $self->pounds - $amount );
183  }
184
185  has taste => (
186    is => 'ro',
187  );
188
189  has brand => (
190    is  => 'ro',
191    isa => sub {
192      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
193    },
194 );
195
196  has pounds => (
197    is  => 'rw',
198    isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
199  );
200
201  1;
202
203 and else where
204
205  my $full = Cat::Food->new(
206     taste  => 'DELICIOUS.',
207     brand  => 'SWEET-TREATZ',
208     pounds => 10,
209  );
210
211  $full->feed_lion;
212
213  say $full->pounds;
214
215 =head1 DESCRIPTION
216
217 This module is an extremely light-weight, high-performance L<Moose> replacement.
218 It also avoids depending on any XS modules to allow simple deployments.  The
219 name C<Moo> is based on the idea that it provides almost -but not quite- two
220 thirds of L<Moose>.
221
222 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility.  See
223 L</INCOMPATIBILITIES> for more details.
224
225 =head1 WHY MOO EXISTS
226
227 If you want a full object system with a rich Metaprotocol, L<Moose> is
228 already wonderful.
229
230 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
231 takes longer to load than most of my Moo based CGI scripts take to run.
232
233 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
234 you want "as little as possible" - which means "no metaprotocol", which is
235 what Moo provides.
236
237 By Moo 1.0 I intend to have Moo's equivalent of L<Any::Moose> built in -
238 if Moose gets loaded, any Moo class or role will act as a Moose equivalent
239 if treated as such.
240
241 Hence - Moo exists as its name - Minimal Object Orientation - with a pledge
242 to make it smooth to upgrade to L<Moose> when you need more than minimal
243 features.
244
245 =head1 Moo and Moose - NEW, EXPERIMENTAL
246
247 If L<Moo> detects L<Moose> being loaded, it will automatically register
248 metaclasses for your L<Moo> and L<Moo::Role> packages, so you should be able
249 to use them in L<Moose> code without it ever realising you aren't using
250 L<Moose> everywhere.
251
252 Extending a L<Moose> class or consuming a L<Moose::Role> should also work.
253
254 So should extending a L<Mouse> class or consuming a L<Mouse::Role>.
255
256 This means that there is no need for anything like L<Any::Moose> for Moo
257 code - Moo and Moose code should simply interoperate without problem. To
258 handle L<Mouse> code, you'll likely need an empty Moo role or class consuming
259 or extending the L<Mouse> stuff since it doesn't register true L<Moose>
260 metaclasses like we do.
261
262 However, these features are new as of 0.91.0 (0.091000) so while serviceable,
263 they are absolutely certain to not be 100% yet; please do report bugs.
264
265 If you need to disable the metaclass creation, add:
266
267   no Moo::sification;
268
269 to your code before Moose is loaded, but bear in mind that this switch is
270 currently global and turns the mechanism off entirely, so don't put this
271 in library code, only in a top level script as a temporary measure while
272 you send a bug report.
273
274 =head1 IMPORTED METHODS
275
276 =head2 new
277
278  Foo::Bar->new( attr1 => 3 );
279
280 or
281
282  Foo::Bar->new({ attr1 => 3 });
283
284 =head2 BUILDARGS
285
286  sub BUILDARGS {
287    my ( $class, @args ) = @_;
288
289    unshift @args, "attr1" if @args % 2 == 1;
290
291    return { @args };
292  };
293
294  Foo::Bar->new( 3 );
295
296 The default implementation of this method accepts a hash or hash reference of
297 named parameters. If it receives a single argument that isn't a hash reference
298 it throws an error.
299
300 You can override this method in your class to handle other types of options
301 passed to the constructor.
302
303 This method should always return a hash reference of named options.
304
305 =head2 BUILD
306
307 Define a C<BUILD> method on your class and the constructor will automatically
308 call the C<BUILD> method from parent down to child after the object has
309 been instantiated.  Typically this is used for object validation or possibly
310 logging.
311
312 =head2 DEMOLISH
313
314 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
315 a C<DESTROY> method is created on first object construction which will call
316 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
317 method from child upwards to parents.
318
319 Note that the C<DESTROY> method is created on first construction of an object
320 of your class in order to not add overhead to classes without C<DEMOLISH>
321 methods; this may prove slightly surprising if you try and define your own.
322
323 =head2 does
324
325  if ($foo->does('Some::Role1')) {
326    ...
327  }
328
329 Returns true if the object composes in the passed role.
330
331 =head1 IMPORTED SUBROUTINES
332
333 =head2 extends
334
335  extends 'Parent::Class';
336
337 Declares base class. Multiple superclasses can be passed for multiple
338 inheritance (but please use roles instead).
339
340 Calling extends more than once will REPLACE your superclasses, not add to
341 them like 'use base' would.
342
343 =head2 with
344
345  with 'Some::Role1';
346
347 or
348
349  with 'Some::Role1', 'Some::Role2';
350
351 Composes one or more L<Moo::Role> (or L<Role::Tiny>) roles into the current
352 class.  An error will be raised if these roles have conflicting methods.
353
354 =head2 has
355
356  has attr => (
357    is => 'ro',
358  );
359
360 Declares an attribute for the class.
361
362 The options for C<has> are as follows:
363
364 =over 2
365
366 =item * is
367
368 B<required>, may be C<ro>, C<lazy>, C<rwp> or C<rw>.
369
370 C<ro> generates an accessor that dies if you attempt to write to it - i.e.
371 a getter only - by defaulting C<reader> to the name of the attribute.
372
373 C<lazy> generates a reader like C<ro>, but also sets C<lazy> to 1 and
374 C<builder> to C<_build_${attribute_name}> to allow on-demand generated
375 attributes.  This feature was my attempt to fix my incompetence when
376 originally designing C<lazy_build>, and is also implemented by
377 L<MooseX::AttributeShortcuts>.
378
379 C<rwp> generates a reader like C<ro>, but also sets C<writer> to
380 C<_set_${attribute_name}> for attributes that are designed to be written
381 from inside of the class, but read-only from outside.
382 This feature comes from L<MooseX::AttributeShortcuts>.
383
384 C<rw> generates a normal getter/setter by defaulting C<accessor> to the
385 name of the attribute.
386
387 =item * isa
388
389 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
390 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
391 one should do
392
393  isa => quote_sub q{
394    die "$_[0] is not a number!" unless looks_like_number $_[0]
395  },
396
397 L<Sub::Quote aware|/SUB QUOTE AWARE>
398
399 Since L<Moo> does B<not> run the C<isa> check before C<coerce> if a coercion
400 subroutine has been supplied, C<isa> checks are not structural to your code
401 and can, if desired, be omitted on non-debug builds (although if this results
402 in an uncaught bug causing your program to break, the L<Moo> authors guarantee
403 nothing except that you get to keep both halves).
404
405 If you want L<MooseX::Types> style named types, look at
406 L<MooX::Types::MooseLike>.
407
408 To cause your C<isa> entries to be automatically mapped to named
409 L<Moose::Meta::TypeConstraint> objects (rather than the default behaviour
410 of creating an anonymous type), set:
411
412   $Moo::HandleMoose::TYPE_MAP{$isa_coderef} = sub {
413     require MooseX::Types::Something;
414     return MooseX::Types::Something::TypeName();
415   };
416
417 Note that this example is purely illustrative; anything that returns a
418 L<Moose::Meta::TypeConstraint> object or something similar enough to it to
419 make L<Moose> happy is fine.
420
421 =item * coerce
422
423 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
424 do something like the following:
425
426  coerce => quote_sub q{
427    $_[0] + 1 unless $_[0] % 2
428  },
429
430 Note that L<Moo> will always fire your coercion - this is to permit
431 isa entries to be used purely for bug trapping, whereas coercions are
432 always structural to your code. We do, however, apply any supplied C<isa>
433 check after the coercion has run to ensure that it returned a valid value.
434
435 L<Sub::Quote aware|/SUB QUOTE AWARE>
436
437 =item * handles
438
439 Takes a string
440
441   handles => 'RobotRole'
442
443 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
444 becomes the list of methods to handle.
445
446 Takes a list of methods
447
448  handles => [ qw( one two ) ]
449
450 Takes a hashref
451
452  handles => {
453    un => 'one',
454  }
455
456 =item * trigger
457
458 Takes a coderef which will get called any time the attribute is set. This
459 includes the constructor. Coderef will be invoked against the object with the
460 new value as an argument.
461
462 If you set this to just C<1>, it generates a trigger which calls the
463 C<_trigger_${attr_name}> method on C<$self>. This feature comes from
464 L<MooseX::AttributeShortcuts>.
465
466 Note that Moose also passes the old value, if any; this feature is not yet
467 supported.
468
469 L<Sub::Quote aware|/SUB QUOTE AWARE>
470
471 =item * default
472
473 Takes a coderef which will get called with $self as its only argument
474 to populate an attribute if no value is supplied to the constructor - or
475 if the attribute is lazy, when the attribute is first retrieved if no
476 value has yet been provided.
477
478 Note that if your default is fired during new() there is no guarantee that
479 other attributes have been populated yet so you should not rely on their
480 existence.
481
482 L<Sub::Quote aware|/SUB QUOTE AWARE>
483
484 =item * predicate
485
486 Takes a method name which will return true if an attribute has a value.
487
488 If you set this to just C<1>, the predicate is automatically named
489 C<has_${attr_name}> if your attribute's name does not start with an
490 underscore, or <_has_${attr_name_without_the_underscore}> if it does.
491 This feature comes from L<MooseX::AttributeShortcuts>.
492
493 =item * builder
494
495 Takes a method name which will be called to create the attribute - functions
496 exactly like default except that instead of calling
497
498   $default->($self);
499
500 Moo will call
501
502   $self->$builder;
503
504 If you set this to just C<1>, the predicate is automatically named
505 C<_build_${attr_name}>.  This feature comes from L<MooseX::AttributeShortcuts>.
506
507 =item * clearer
508
509 Takes a method name which will clear the attribute.
510
511 If you set this to just C<1>, the clearer is automatically named
512 C<clear_${attr_name}> if your attribute's name does not start with an
513 underscore, or <_clear_${attr_name_without_the_underscore}> if it does.
514 This feature comes from L<MooseX::AttributeShortcuts>.
515
516 =item * lazy
517
518 B<Boolean>.  Set this if you want values for the attribute to be grabbed
519 lazily.  This is usually a good idea if you have a L</builder> which requires
520 another attribute to be set.
521
522 =item * required
523
524 B<Boolean>.  Set this if the attribute must be passed on instantiation.
525
526 =item * reader
527
528 The value of this attribute will be the name of the method to get the value of
529 the attribute.  If you like Java style methods, you might set this to
530 C<get_foo>
531
532 =item * writer
533
534 The value of this attribute will be the name of the method to set the value of
535 the attribute.  If you like Java style methods, you might set this to
536 C<set_foo>
537
538 =item * weak_ref
539
540 B<Boolean>.  Set this if you want the reference that the attribute contains to
541 be weakened; use this when circular references are possible, which will cause
542 leaks.
543
544 =item * init_arg
545
546 Takes the name of the key to look for at instantiation time of the object.  A
547 common use of this is to make an underscored attribute have a non-underscored
548 initialization name. C<undef> means that passing the value in on instantiation
549 is ignored.
550
551 =back
552
553 =head2 before
554
555  before foo => sub { ... };
556
557 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
558 documentation.
559
560 =head2 around
561
562  around foo => sub { ... };
563
564 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
565 documentation.
566
567 =head2 after
568
569  after foo => sub { ... };
570
571 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
572 documentation.
573
574 =head1 SUB QUOTE AWARE
575
576 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
577 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
578 aware can take advantage of this.
579
580 =head1 INCOMPATIBILITIES WITH MOOSE
581
582 There is no built in type system.  C<isa> is verified with a coderef, if you
583 need complex types, just make a library of coderefs, or better yet, functions
584 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
585 to L<MooseX::Types::Moose> so that you can write
586
587   has days_to_live => (is => 'ro', isa => Int);
588
589 and have it work with both; it is hoped that providing only subrefs as an
590 API will encourage the use of other type systems as well, since it's
591 probably the weakest part of Moose design-wise.
592
593 C<initializer> is not supported in core since the author considers it to be a
594 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
595 C<coerce> are more likely to be able to fulfill your needs.
596
597 There is no meta object.  If you need this level of complexity you wanted
598 L<Moose> - Moo succeeds at being small because it explicitly does not
599 provide a metaprotocol. However, if you load L<Moose>, then
600
601   Class::MOP::class_of($moo_class_or_role)
602
603 will return an appropriate metaclass pre-populated by L<Moo>.
604
605 No support for C<super>, C<override>, C<inner>, or C<augment> - the author
606 considers augment to be a bad idea, and override can be translated:
607
608   override foo => sub {
609     ...
610     super();
611     ...
612   };
613
614   around foo => sub {
615     my ($orig, $self) = (shift, shift);
616     ...
617     $self->$orig(@_);
618     ...
619   };
620
621 The C<dump> method is not provided by default. The author suggests loading
622 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
623 using C<$obj-E<gt>$::Dwarn()> instead.
624
625 L</default> only supports coderefs, because doing otherwise is usually a
626 mistake anyway.
627
628 C<lazy_build> is not supported; you are instead encouraged to use the
629 C<is => 'lazy'> option supported by L<Moo> and L<MooseX::AttributeShortcuts>.
630
631 C<auto_deref> is not supported since the author considers it a bad idea.
632
633 C<documentation> will show up in a L<Moose> metaclass created from your class
634 but is otherwise ignored. Then again, L<Moose> ignores it as well, so this
635 is arguably not an incompatibility.
636
637 Since C<coerce> does not require C<isa> to be defined but L<Moose> does
638 require it, the metaclass inflation for coerce-alone is a trifle insane
639 and if you attempt to subtype the result will almost certainly break.
640
641 Handling of warnings: when you C<use Moo> we enable FATAL warnings.  The nearest
642 similar invocation for L<Moose> would be:
643
644   use Moose;
645   use warnings FATAL => "all";
646
647 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
648 reduce common boilerplate.  The set of shortcuts is the same as in the L<Moose>
649 module L<MooseX::AttributeShortcuts> as of its version 0.009+.  So if you:
650
651     package MyClass;
652     use Moo;
653
654 The nearest L<Moose> invocation would be:
655
656     package MyClass;
657
658     use Moose;
659     use warnings FATAL => "all";
660     use MooseX::AttributeShortcuts;
661
662 or, if you're inheriting from a non-Moose class,
663
664     package MyClass;
665
666     use Moose;
667     use MooseX::NonMoose;
668     use warnings FATAL => "all";
669     use MooseX::AttributeShortcuts;
670
671 Finally, Moose requires you to call
672
673     __PACKAGE__->meta->make_immutable;
674
675 at the end of your class to get an inlined (i.e. not horribly slow)
676 constructor. Moo does it automatically the first time ->new is called
677 on your class.
678
679 =head1 SUPPORT
680
681 Users' IRC: #moose on irc.perl.org
682
683 Development and contribution IRC: #web-simple on irc.perl.org
684
685 =head1 AUTHOR
686
687 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
688
689 =head1 CONTRIBUTORS
690
691 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
692
693 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
694
695 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
696
697 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
698
699 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
700
701 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
702
703 ajgb - Alex J. G. BurzyƄski (cpan:AJGB) <ajgb@cpan.org>
704
705 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
706
707 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
708
709 =head1 COPYRIGHT
710
711 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
712 as listed above.
713
714 =head1 LICENSE
715
716 This library is free software and may be distributed under the same terms
717 as perl itself.
718
719 =cut