lib/Moo.pm

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