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_016'; # 0.9.16
   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. This
 329 includes the constructor. Coderef will be invoked against the object with the
 330 new value as an argument.
 331
 332 Note that Moose also passes the old value, if any; this feature is not yet
 333 supported.
 334
 335 L<Sub::Quote aware|/SUB QUOTE AWARE>
 336
 337 =item * default
 338
 339 Takes a coderef which will get called with $self as its only argument
 340 to populate an attribute if no value is supplied to the constructor - or
 341 if the attribute is lazy, when the attribute is first retrieved if no
 342 value has yet been provided.
 343
 344 Note that if your default is fired during new() there is no guarantee that
 345 other attributes have been populated yet so you should not rely on their
 346 existence.
 347
 348 L<Sub::Quote aware|/SUB QUOTE AWARE>
 349
 350 =item * predicate
 351
 352 Takes a method name which will return true if an attribute has a value.
 353
 354 A common example of this would be to call it C<has_$foo>, implying that the
 355 object has a C<$foo> set.
 356
 357 =item * builder
 358
 359 Takes a method name which will be called to create the attribute - functions
 360 exactly like default except that instead of calling
 361
 362   $default->($self);
 363
 364 Moo will call
 365
 366   $self->$builder;
 367
 368 =item * clearer
 369
 370 Takes a method name which will clear the attribute.
 371
 372 =item * lazy
 373
 374 B<Boolean>.  Set this if you want values for the attribute to be grabbed
 375 lazily.  This is usually a good idea if you have a L</builder> which requires
 376 another attribute to be set.
 377
 378 =item * required
 379
 380 B<Boolean>.  Set this if the attribute must be passed on instantiation.
 381
 382 =item * reader
 383
 384 The value of this attribute will be the name of the method to get the value of
 385 the attribute.  If you like Java style methods, you might set this to
 386 C<get_foo>
 387
 388 =item * writer
 389
 390 The value of this attribute will be the name of the method to set the value of
 391 the attribute.  If you like Java style methods, you might set this to
 392 C<set_foo>
 393
 394 =item * weak_ref
 395
 396 B<Boolean>.  Set this if you want the reference that the attribute contains to
 397 be weakened; use this when circular references are possible, which will cause
 398 leaks.
 399
 400 =item * init_arg
 401
 402 Takes the name of the key to look for at instantiation time of the object.  A
 403 common use of this is to make an underscored attribute have a non-underscored
 404 initialization name. C<undef> means that passing the value in on instantiation
 405
 406 =back
 407
 408 =head2 before
 409
 410  before foo => sub { ... };
 411
 412 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
 413 documentation.
 414
 415 =head2 around
 416
 417  around foo => sub { ... };
 418
 419 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
 420 documentation.
 421
 422 =head2 after
 423
 424  after foo => sub { ... };
 425
 426 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
 427 documentation.
 428
 429 =head1 SUB QUOTE AWARE
 430
 431 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 432 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 433 aware can take advantage of this.
 434
 435 =head1 INCOMPATIBILITIES WITH MOOSE
 436
 437 You can only compose one role at a time.  If your application is large or
 438 complex enough to warrant complex composition, you wanted L<Moose>.  Note that
 439 this does not mean you can only compose one role per class -
 440
 441   with 'FirstRole';
 442   with 'SecondRole';
 443
 444 is absolutely fine, there's just currently no equivalent of Moose's
 445
 446   with 'FirstRole', 'SecondRole';
 447
 448 which composes the two roles together, and then applies them.
 449
 450 There is no built in type system.  C<isa> is verified with a coderef, if you
 451 need complex types, just make a library of coderefs, or better yet, functions
 452 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
 453 to L<MooseX::Types::Moose> so that you can write
 454
 455   has days_to_live => (is => 'ro', isa => Int);
 456
 457 and have it work with both; it is hoped that providing only subrefs as an
 458 API will encourage the use of other type systems as well, since it's
 459 probably the weakest part of Moose design-wise.
 460
 461 C<initializer> is not supported in core since the author considers it to be a
 462 bad idea but may be supported by an extension in future. Meanwhile C<trigger> or
 463 C<coerce> are more likely to be able to fulfill your needs.
 464
 465 There is no meta object.  If you need this level of complexity you wanted
 466 L<Moose> - Moo succeeds at being small because it explicitly does not
 467 provide a metaprotocol.
 468
 469 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
 470 be handled by around albeit with a little more typing, and the author considers
 471 augment to be a bad idea.
 472
 473 The C<dump> method is not provided by default. The author suggests loading
 474 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
 475 using C<$obj-E<gt>$::Dwarn()> instead.
 476
 477 L</default> only supports coderefs, because doing otherwise is usually a
 478 mistake anyway.
 479
 480 C<lazy_build> is not supported per se, but of course it will work if you
 481 manually set all the options it implies.
 482
 483 C<auto_deref> is not supported since the author considers it a bad idea.
 484
 485 C<documentation> is not supported since it's a very poor replacement for POD.
 486
 487 Handling of warnings: when you C<use Moo> we enable FATAL warnings.  The nearest
 488 similar invocation for L<Moose> would be:
 489
 490   use Moose;
 491   use warnings FATAL => "all";
 492
 493 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
 494 reduce common boilerplate.  The set of shortcuts is the same as in the L<Moose>
 495 module L<MooseX::AttributeShortcuts>.  So if you:
 496
 497     package MyClass;
 498     use Moo;
 499
 500 The nearest L<Moose> invocation would be:
 501
 502     package MyClass;
 503
 504     use Moose;
 505     use warnings FATAL => "all";
 506     use MooseX::AttributeShortcuts;
 507
 508 or, if you're inheriting from a non-Moose class,
 509
 510     package MyClass;
 511
 512     use Moose;
 513     use MooseX::NonMoose;
 514     use warnings FATAL => "all";
 515     use MooseX::AttributeShortcuts;
 516
 517 Finally, Moose requires you to call
 518
 519     __PACKAGE__->meta->make_immutable;
 520
 521 at the end of your class to get an inlined (i.e. not horribly slow)
 522 constructor. Moo does it automatically the first time ->new is called
 523 on your class.
 524
 525 =head1 AUTHOR
 526
 527 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 528
 529 =head1 CONTRIBUTORS
 530
 531 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
 532
 533 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
 534
 535 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
 536
 537 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
 538
 539 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
 540
 541 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
 542
 543 ajgb - Alex J. G. Burzyński (cpan:AJGB) <ajgb@cpan.org>
 544
 545 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
 546
 547 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
 548
 549 =head1 COPYRIGHT
 550
 551 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
 552 as listed above.
 553
 554 =head1 LICENSE
 555
 556 This library is free software and may be distributed under the same terms
 557 as perl itself.
 558
 559 =cut