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     Moo::Role->apply_roles_to_package($target, $_[0]);
  37   };
  38   $MAKERS{$target} = {};
  39   *{_getglob("${target}::has")} = sub {
  40     my ($name, %spec) = @_;
  41     ($MAKERS{$target}{accessor} ||= do {
  42       require Method::Generate::Accessor;
  43       Method::Generate::Accessor->new
  44     })->generate_method($target, $name, \%spec);
  45     $class->_constructor_maker_for($target)
  46           ->register_attribute_specs($name, \%spec);
  47   };
  48   foreach my $type (qw(before after around)) {
  49     *{_getglob "${target}::${type}"} = sub {
  50       require Class::Method::Modifiers;
  51       _install_modifier($target, $type, @_);
  52     };
  53   }
  54   {
  55     no strict 'refs';
  56     @{"${target}::ISA"} = do {
  57       require Moo::Object; ('Moo::Object');
  58     } unless @{"${target}::ISA"};
  59   }
  60   if ($INC{'Moo/HandleMoose.pm'}) {
  61     Moo::HandleMoose::inject_fake_metaclass_for($target);
  62   }
  63 }
  64
  65 sub _constructor_maker_for {
  66   my ($class, $target, $select_super) = @_;
  67   return unless $MAKERS{$target};
  68   $MAKERS{$target}{constructor} ||= do {
  69     require Method::Generate::Constructor;
  70     require Sub::Defer;
  71     my ($moo_constructor, $con);
  72
  73     if ($select_super && $MAKERS{$select_super}) {
  74       $moo_constructor = 1;
  75       $con = $MAKERS{$select_super}{constructor};
  76     } else {
  77       my $t_new = $target->can('new');
  78       if ($t_new) {
  79         if ($t_new == Moo::Object->can('new')) {
  80           $moo_constructor = 1;
  81         } elsif (my $defer_target = (Sub::Defer::defer_info($t_new)||[])->[0]) {
  82           my ($pkg) = ($defer_target =~ /^(.*)::[^:]+$/);
  83           if ($MAKERS{$pkg}) {
  84             $moo_constructor = 1;
  85             $con = $MAKERS{$pkg}{constructor};
  86           }
  87         }
  88       } else {
  89         $moo_constructor = 1; # no other constructor, make a Moo one
  90       }
  91     };
  92     Method::Generate::Constructor
  93       ->new(
  94         package => $target,
  95         accessor_generator => do {
  96           require Method::Generate::Accessor;
  97           Method::Generate::Accessor->new;
  98         },
  99         construction_string => (
 100           $moo_constructor
 101             ? ($con ? $con->construction_string : undef)
 102             : ('$class->'.$target.'::SUPER::new(@_)')
 103         ),
 104         subconstructor_generator => (
 105           $class.'->_constructor_maker_for($class,'.perlstring($target).')'
 106         ),
 107       )
 108       ->install_delayed
 109       ->register_attribute_specs(%{$con?$con->all_attribute_specs:{}})
 110   }
 111 }
 112
 113 1;
 114 =pod
 115
 116 =encoding utf-8
 117
 118 =head1 NAME
 119
 120 Moo - Minimalist Object Orientation (with Moose compatiblity)
 121
 122 =head1 SYNOPSIS
 123
 124  package Cat::Food;
 125
 126  use Moo;
 127  use Sub::Quote;
 128
 129  sub feed_lion {
 130    my $self = shift;
 131    my $amount = shift || 1;
 132
 133    $self->pounds( $self->pounds - $amount );
 134  }
 135
 136  has taste => (
 137    is => 'ro',
 138  );
 139
 140  has brand => (
 141    is  => 'ro',
 142    isa => sub {
 143      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
 144    },
 145 );
 146
 147  has pounds => (
 148    is  => 'rw',
 149    isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
 150  );
 151
 152  1;
 153
 154 and else where
 155
 156  my $full = Cat::Food->new(
 157     taste  => 'DELICIOUS.',
 158     brand  => 'SWEET-TREATZ',
 159     pounds => 10,
 160  );
 161
 162  $full->feed_lion;
 163
 164  say $full->pounds;
 165
 166 =head1 DESCRIPTION
 167
 168 This module is an extremely light-weight, high-performance L<Moose> replacement.
 169 It also avoids depending on any XS modules to allow simple deployments.  The
 170 name C<Moo> is based on the idea that it provides almost -but not quite- two
 171 thirds of L<Moose>.
 172
 173 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility.  See
 174 L</INCOMPATIBILITIES> for more details.
 175
 176 =head1 WHY MOO EXISTS
 177
 178 If you want a full object system with a rich Metaprotocol, L<Moose> is
 179 already wonderful.
 180
 181 I've tried several times to use L<Mouse> but it's 3x the size of Moo and
 182 takes longer to load than most of my Moo based CGI scripts take to run.
 183
 184 If you don't want L<Moose>, you don't want "less metaprotocol" like L<Mouse>,
 185 you want "as little as possible" - which means "no metaprotocol", which is
 186 what Moo provides.
 187
 188 By Moo 1.0 I intend to have Moo's equivalent of L<Any::Moose> built in -
 189 if Moose gets loaded, any Moo class or role will act as a Moose equivalent
 190 if treated as such.
 191
 192 Hence - Moo exists as its name - Minimal Object Orientation - with a pledge
 193 to make it smooth to upgrade to L<Moose> when you need more than minimal
 194 features.
 195
 196 =head1 IMPORTED METHODS
 197
 198 =head2 new
 199
 200  Foo::Bar->new( attr1 => 3 );
 201
 202 or
 203
 204  Foo::Bar->new({ attr1 => 3 });
 205
 206 =head2 BUILDARGS
 207
 208  around BUILDARGS => sub {
 209    my $orig = shift;
 210    my ( $class, @args ) = @_;
 211
 212    unshift @args, "attr1" if @args % 2 == 1;
 213
 214    return $class->$orig(@args);
 215  };
 216
 217  Foo::Bar->new( 3 );
 218
 219 The default implementation of this method accepts a hash or hash reference of
 220 named parameters. If it receives a single argument that isn't a hash reference
 221 it throws an error.
 222
 223 You can override this method in your class to handle other types of options
 224 passed to the constructor.
 225
 226 This method should always return a hash reference of named options.
 227
 228 =head2 BUILD
 229
 230 Define a C<BUILD> method on your class and the constructor will automatically
 231 call the C<BUILD> method from parent down to child after the object has
 232 been instantiated.  Typically this is used for object validation or possibly
 233 logging.
 234
 235 =head2 DEMOLISH
 236
 237 If you have a C<DEMOLISH> method anywhere in your inheritance hierarchy,
 238 a C<DESTROY> method is created on first object construction which will call
 239 C<< $instance->DEMOLISH($in_global_destruction) >> for each C<DEMOLISH>
 240 method from child upwards to parents.
 241
 242 Note that the C<DESTROY> method is created on first construction of an object
 243 of your class in order to not add overhead to classes without C<DEMOLISH>
 244 methods; this may prove slightly surprising if you try and define your own.
 245
 246 =head2 does
 247
 248  if ($foo->does('Some::Role1')) {
 249    ...
 250  }
 251
 252 Returns true if the object composes in the passed role.
 253
 254 =head1 IMPORTED SUBROUTINES
 255
 256 =head2 extends
 257
 258  extends 'Parent::Class';
 259
 260 Declares base class. Multiple superclasses can be passed for multiple
 261 inheritance (but please use roles instead).
 262
 263 Calling extends more than once will REPLACE your superclasses, not add to
 264 them like 'use base' would.
 265
 266 =head2 with
 267
 268  with 'Some::Role1';
 269  with 'Some::Role2';
 270
 271 Composes a L<Role::Tiny> into current class.  Only one role may be composed in
 272 at a time to allow the code to remain as simple as possible.
 273
 274 =head2 has
 275
 276  has attr => (
 277    is => 'ro',
 278  );
 279
 280 Declares an attribute for the class.
 281
 282 The options for C<has> are as follows:
 283
 284 =over 2
 285
 286 =item * is
 287
 288 B<required>, must be C<ro> or C<rw>.  Unsurprisingly, C<ro> generates an
 289 accessor that will not respond to arguments; to be clear: a getter only. C<rw>
 290 will create a perlish getter/setter.
 291
 292 =item * isa
 293
 294 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
 295 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
 296 one should do
 297
 298  isa => quote_sub q{
 299    die "$_[0] is not a number!" unless looks_like_number $_[0]
 300  },
 301
 302 L<Sub::Quote aware|/SUB QUOTE AWARE>
 303
 304 =item * coerce
 305
 306 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
 307 do something like the following:
 308
 309  coerce => quote_sub q{
 310    $_[0] + 1 unless $_[0] % 2
 311  },
 312
 313 Coerce does not require C<isa> to be defined.
 314
 315 L<Sub::Quote aware|/SUB QUOTE AWARE>
 316
 317 =item * handles
 318
 319 Takes a string
 320
 321   handles => 'RobotRole'
 322
 323 Where C<RobotRole> is a role (L<Moo::Role>) that defines an interface which
 324 becomes the list of methods to handle.
 325
 326 Takes a list of methods
 327
 328  handles => [ qw( one two ) ]
 329
 330 Takes a hashref
 331
 332  handles => {
 333    un => 'one',
 334  }
 335
 336 =item * trigger
 337
 338 Takes a coderef which will get called any time the attribute is set. Coderef
 339 will be invoked against the object with the new value as an argument.
 340
 341 Note that Moose also passes the old value, if any; this feature is not yet
 342 supported.
 343
 344 L<Sub::Quote aware|/SUB QUOTE AWARE>
 345
 346 =item * default
 347
 348 Takes a coderef which will get called with $self as its only argument
 349 to populate an attribute if no value is supplied to the constructor - or
 350 if the attribute is lazy, when the attribute is first retrieved if no
 351 value has yet been provided.
 352
 353 Note that if your default is fired during new() there is no guarantee that
 354 other attributes have been populated yet so you should not rely on their
 355 existence.
 356
 357 L<Sub::Quote aware|/SUB QUOTE AWARE>
 358
 359 =item * predicate
 360
 361 Takes a method name which will return true if an attribute has a value.
 362
 363 A common example of this would be to call it C<has_$foo>, implying that the
 364 object has a C<$foo> set.
 365
 366 =item * builder
 367
 368 Takes a method name which will be called to create the attribute - functions
 369 exactly like default except that instead of calling
 370
 371   $default->($self);
 372
 373 Moo will call
 374
 375   $self->$builder;
 376
 377 =item * clearer
 378
 379 Takes a method name which will clear the attribute.
 380
 381 =item * lazy
 382
 383 B<Boolean>.  Set this if you want values for the attribute to be grabbed
 384 lazily.  This is usually a good idea if you have a L</builder> which requires
 385 another attribute to be set.
 386
 387 =item * required
 388
 389 B<Boolean>.  Set this if the attribute must be passed on instantiation.
 390
 391 =item * reader
 392
 393 The value of this attribute will be the name of the method to get the value of
 394 the attribute.  If you like Java style methods, you might set this to
 395 C<get_foo>
 396
 397 =item * writer
 398
 399 The value of this attribute will be the name of the method to set the value of
 400 the attribute.  If you like Java style methods, you might set this to
 401 C<set_foo>
 402
 403 =item * weak_ref
 404
 405 B<Boolean>.  Set this if you want the reference that the attribute contains to
 406 be weakened; use this when circular references are possible, which will cause
 407 leaks.
 408
 409 =item * init_arg
 410
 411 Takes the name of the key to look for at instantiation time of the object.  A
 412 common use of this is to make an underscored attribute have a non-underscored
 413 initialization name. C<undef> means that passing the value in on instantiation
 414
 415 =back
 416
 417 =head2 before
 418
 419  before foo => sub { ... };
 420
 421 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
 422 documentation.
 423
 424 =head2 around
 425
 426  around foo => sub { ... };
 427
 428 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
 429 documentation.
 430
 431 =head2 after
 432
 433  after foo => sub { ... };
 434
 435 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
 436 documentation.
 437
 438 =head1 SUB QUOTE AWARE
 439
 440 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 441 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 442 aware can take advantage of this.
 443
 444 =head1 INCOMPATIBILITIES WITH MOOSE
 445
 446 You can only compose one role at a time.  If your application is large or
 447 complex enough to warrant complex composition, you wanted L<Moose>.  Note that
 448 this does not mean you can only compose one role per class -
 449
 450   with 'FirstRole';
 451   with 'SecondRole';
 452
 453 is absolutely fine, there's just currently no equivalent of Moose's
 454
 455   with 'FirstRole', 'SecondRole';
 456
 457 which composes the two roles together, and then applies them.
 458
 459 There is no built in type system.  C<isa> is verified with a coderef, if you
 460 need complex types, just make a library of coderefs, or better yet, functions
 461 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
 462 to L<MooseX::Types::Moose> so that you can write
 463
 464   has days_to_live => (is => 'ro', isa => Int);
 465
 466 and have it work with both; it is hoped that providing only subrefs as an
 467 API will encourage the use of other type systems as well, since it's
 468 probably the weakest part of Moose design-wise.
 469
 470 C<initializer> is not supported in core since the author considers it to be a
 471 bad idea but may be supported by an extension in future.
 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