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