lib/Moo.pm

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