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     ($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 This means that there is no need for anything like L<Any::Moose> for Moo
 204 code - Moo and Moose code should simply interoperate without problem.
 205
 206 However, these features are new as of 0.91.0 (0.091000) so while serviceable,
 207 they are absolutely certain to not be 100% yet; please do report bugs.
 208
 209 If you need to disable the metaclass creation, add:
 210
 211   no Moo::sification;
 212
 213 to your code before Moose is loaded, but bear in mind that this switch is
 214 currently global and turns the mechanism off entirely, so don't put this
 215 in library code, only in a top level script as a temporary measure while
 216 you send a bug report.
 217
 218 =head1 IMPORTED METHODS
 219
 220 =head2 new
 221
 222  Foo::Bar->new( attr1 => 3 );
 223
 224 or
 225
 226  Foo::Bar->new({ attr1 => 3 });
 227
 228 =head2 BUILDARGS
 229
 230  sub BUILDARGS {
 231    my ( $class, @args ) = @_;
 232
 233    unshift @args, "attr1" if @args % 2 == 1;
 234
 235    return { @args };
 236  };
 237
 238  Foo::Bar->new( 3 );
 239
 240 The default implementation of this method accepts a hash or hash reference of
 241 named parameters. If it receives a single argument that isn't a hash reference
 242 it throws an error.
 243
 244 You can override this method in your class to handle other types of options
 245 passed to the constructor.
 246
 247 This method should always return a hash reference of named options.
 248
 249 =head2 BUILD
 250
 251 Define a C<BUILD> method on your class and the constructor will automatically
 252 call the C<BUILD> method from parent down to child after the object has
 253 been instantiated.  Typically this is used for object validation or possibly
 254 logging.
 255
 256 =head2 DEMOLISH
 257
 258 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
 259 a C<DESTROY> method is created on first object construction which will call
 260 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
 261 method from child upwards to parents.
 262
 263 Note that the C<DESTROY> method is created on first construction of an object
 264 of your class in order to not add overhead to classes without C<DEMOLISH>
 265 methods; this may prove slightly surprising if you try and define your own.
 266
 267 =head2 does
 268
 269  if ($foo->does('Some::Role1')) {
 270    ...
 271  }
 272
 273 Returns true if the object composes in the passed role.
 274
 275 =head1 IMPORTED SUBROUTINES
 276
 277 =head2 extends
 278
 279  extends 'Parent::Class';
 280
 281 Declares base class. Multiple superclasses can be passed for multiple
 282 inheritance (but please use roles instead).
 283
 284 Calling extends more than once will REPLACE your superclasses, not add to
 285 them like 'use base' would.
 286
 287 =head2 with
 288
 289  with 'Some::Role1';
 290  with 'Some::Role2';
 291
 292 Composes a L<Role::Tiny> into current class.  Only one role may be composed in
 293 at a time to allow the code to remain as simple as possible.
 294
 295 =head2 has
 296
 297  has attr => (
 298    is => 'ro',
 299  );
 300
 301 Declares an attribute for the class.
 302
 303 The options for C<has> are as follows:
 304
 305 =over 2
 306
 307 =item * is
 308
 309 B<required>, must be C<ro> or C<rw>.  Unsurprisingly, C<ro> generates an
 310 accessor that will not respond to arguments; to be clear: a getter only. C<rw>
 311 will create a perlish getter/setter.
 312
 313 =item * isa
 314
 315 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
 316 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
 317 one should do
 318
 319  isa => quote_sub q{
 320    die "$_[0] is not a number!" unless looks_like_number $_[0]
 321  },
 322
 323 L<Sub::Quote aware|/SUB QUOTE AWARE>
 324
 325 =item * coerce
 326
 327 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
 328 do something like the following:
 329
 330  coerce => quote_sub q{
 331    $_[0] + 1 unless $_[0] % 2
 332  },
 333
 334 Coerce does not require C<isa> to be defined.
 335
 336 L<Sub::Quote aware|/SUB QUOTE AWARE>
 337
 338 =item * handles
 339
 340 Takes a string
 341
 342   handles => 'RobotRole'
 343
 344 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
 345 becomes the list of methods to handle.
 346
 347 Takes a list of methods
 348
 349  handles => [ qw( one two ) ]
 350
 351 Takes a hashref
 352
 353  handles => {
 354    un => 'one',
 355  }
 356
 357 =item * trigger
 358
 359 Takes a coderef which will get called any time the attribute is set. This
 360 includes the constructor. Coderef will be invoked against the object with the
 361 new value as an argument.
 362
 363 Note that Moose also passes the old value, if any; this feature is not yet
 364 supported.
 365
 366 L<Sub::Quote aware|/SUB QUOTE AWARE>
 367
 368 =item * default
 369
 370 Takes a coderef which will get called with $self as its only argument
 371 to populate an attribute if no value is supplied to the constructor - or
 372 if the attribute is lazy, when the attribute is first retrieved if no
 373 value has yet been provided.
 374
 375 Note that if your default is fired during new() there is no guarantee that
 376 other attributes have been populated yet so you should not rely on their
 377 existence.
 378
 379 L<Sub::Quote aware|/SUB QUOTE AWARE>
 380
 381 =item * predicate
 382
 383 Takes a method name which will return true if an attribute has a value.
 384
 385 A common example of this would be to call it C<has_$foo>, implying that the
 386 object has a C<$foo> set.
 387
 388 =item * builder
 389
 390 Takes a method name which will be called to create the attribute - functions
 391 exactly like default except that instead of calling
 392
 393   $default->($self);
 394
 395 Moo will call
 396
 397   $self->$builder;
 398
 399 =item * clearer
 400
 401 Takes a method name which will clear the attribute.
 402
 403 =item * lazy
 404
 405 B<Boolean>.  Set this if you want values for the attribute to be grabbed
 406 lazily.  This is usually a good idea if you have a L</builder> which requires
 407 another attribute to be set.
 408
 409 =item * required
 410
 411 B<Boolean>.  Set this if the attribute must be passed on instantiation.
 412
 413 =item * reader
 414
 415 The value of this attribute will be the name of the method to get the value of
 416 the attribute.  If you like Java style methods, you might set this to
 417 C<get_foo>
 418
 419 =item * writer
 420
 421 The value of this attribute will be the name of the method to set the value of
 422 the attribute.  If you like Java style methods, you might set this to
 423 C<set_foo>
 424
 425 =item * weak_ref
 426
 427 B<Boolean>.  Set this if you want the reference that the attribute contains to
 428 be weakened; use this when circular references are possible, which will cause
 429 leaks.
 430
 431 =item * init_arg
 432
 433 Takes the name of the key to look for at instantiation time of the object.  A
 434 common use of this is to make an underscored attribute have a non-underscored
 435 initialization name. C<undef> means that passing the value in on instantiation
 436
 437 =back
 438
 439 =head2 before
 440
 441  before foo => sub { ... };
 442
 443 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
 444 documentation.
 445
 446 =head2 around
 447
 448  around foo => sub { ... };
 449
 450 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
 451 documentation.
 452
 453 =head2 after
 454
 455  after foo => sub { ... };
 456
 457 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
 458 documentation.
 459
 460 =head1 SUB QUOTE AWARE
 461
 462 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 463 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 464 aware can take advantage of this.
 465
 466 =head1 INCOMPATIBILITIES WITH MOOSE
 467
 468 You can only compose one role at a time.  If your application is large or
 469 complex enough to warrant complex composition, you wanted L<Moose>.  Note that
 470 this does not mean you can only compose one role per class -
 471
 472   with 'FirstRole';
 473   with 'SecondRole';
 474
 475 is absolutely fine, there's just currently no equivalent of Moose's
 476
 477   with 'FirstRole', 'SecondRole';
 478
 479 which composes the two roles together, and then applies them.
 480
 481 There is no built in type system.  C<isa> is verified with a coderef, if you
 482 need complex types, just make a library of coderefs, or better yet, functions
 483 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
 484 to L<MooseX::Types::Moose> so that you can write
 485
 486   has days_to_live => (is => 'ro', isa => Int);
 487
 488 and have it work with both; it is hoped that providing only subrefs as an
 489 API will encourage the use of other type systems as well, since it's
 490 probably the weakest part of Moose design-wise.
 491
 492 C<initializer> is not supported in core since the author considers it to be a
 493 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
 494 C<coerce> are more likely to be able to fulfill your needs.
 495
 496 There is no meta object.  If you need this level of complexity you wanted
 497 L<Moose> - Moo succeeds at being small because it explicitly does not
 498 provide a metaprotocol.
 499
 500 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
 501 be handled by around albeit with a little more typing, and the author considers
 502 augment to be a bad idea.
 503
 504 The C<dump> method is not provided by default. The author suggests loading
 505 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
 506 using C<$obj-E<gt>$::Dwarn()> instead.
 507
 508 L</default> only supports coderefs, because doing otherwise is usually a
 509 mistake anyway.
 510
 511 C<lazy_build> is not supported per se, but of course it will work if you
 512 manually set all the options it implies.
 513
 514 C<auto_deref> is not supported since the author considers it a bad idea.
 515
 516 C<documentation> is not supported since it's a very poor replacement for POD.
 517
 518 Handling of warnings: when you C<use Moo> we enable FATAL warnings.  The nearest
 519 similar invocation for L<Moose> would be:
 520
 521   use Moose;
 522   use warnings FATAL => "all";
 523
 524 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
 525 reduce common boilerplate.  The set of shortcuts is the same as in the L<Moose>
 526 module L<MooseX::AttributeShortcuts> as of its version 0.009+.  So if you:
 527
 528     package MyClass;
 529     use Moo;
 530
 531 The nearest L<Moose> invocation would be:
 532
 533     package MyClass;
 534
 535     use Moose;
 536     use warnings FATAL => "all";
 537     use MooseX::AttributeShortcuts;
 538
 539 or, if you're inheriting from a non-Moose class,
 540
 541     package MyClass;
 542
 543     use Moose;
 544     use MooseX::NonMoose;
 545     use warnings FATAL => "all";
 546     use MooseX::AttributeShortcuts;
 547
 548 Finally, Moose requires you to call
 549
 550     __PACKAGE__->meta->make_immutable;
 551
 552 at the end of your class to get an inlined (i.e. not horribly slow)
 553 constructor. Moo does it automatically the first time ->new is called
 554 on your class.
 555
 556 =head1 SUPPORT
 557
 558 IRC: #web-simple on irc.perl.org
 559
 560 =head1 AUTHOR
 561
 562 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 563
 564 =head1 CONTRIBUTORS
 565
 566 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
 567
 568 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
 569
 570 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
 571
 572 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
 573
 574 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
 575
 576 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
 577
 578 ajgb - Alex J. G. Burzyński (cpan:AJGB) <ajgb@cpan.org>
 579
 580 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
 581
 582 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
 583
 584 =head1 COPYRIGHT
 585
 586 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
 587 as listed above.
 588
 589 =head1 LICENSE
 590
 591 This library is free software and may be distributed under the same terms
 592 as perl itself.
 593
 594 =cut