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