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