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