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