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