lib/Moo.pm

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