lib/Moo.pm

   1 package Moo;
   2
   3 use strictures 1;
   4 use Moo::_Utils;
   5
   6 our $VERSION = '0.009001'; # 0.9.1
   7 $VERSION = eval $VERSION;
   8
   9 our %MAKERS;
  10
  11 sub import {
  12   my $target = caller;
  13   my $class = shift;
  14   strictures->import;
  15   return if $MAKERS{$target}; # already exported into this package
  16   *{_getglob("${target}::extends")} = sub {
  17     _load_module($_) for @_;
  18     # Can't do *{...} = \@_ or 5.10.0's mro.pm stops seeing @ISA
  19     @{*{_getglob("${target}::ISA")}{ARRAY}} = @_;
  20   };
  21   *{_getglob("${target}::with")} = sub {
  22     require Moo::Role;
  23     die "Only one role supported at a time by with" if @_ > 1;
  24     Moo::Role->apply_role_to_package($target, $_[0]);
  25   };
  26   $MAKERS{$target} = {};
  27   *{_getglob("${target}::has")} = sub {
  28     my ($name, %spec) = @_;
  29     ($MAKERS{$target}{accessor} ||= do {
  30       require Method::Generate::Accessor;
  31       Method::Generate::Accessor->new
  32     })->generate_method($target, $name, \%spec);
  33     $class->_constructor_maker_for($target)
  34           ->register_attribute_specs($name, \%spec);
  35   };
  36   foreach my $type (qw(before after around)) {
  37     *{_getglob "${target}::${type}"} = sub {
  38       require Class::Method::Modifiers;
  39       _install_modifier($target, $type, @_);
  40     };
  41   }
  42   {
  43     no strict 'refs';
  44     @{"${target}::ISA"} = do {
  45       require Moo::Object; ('Moo::Object');
  46     } unless @{"${target}::ISA"};
  47   }
  48 }
  49
  50 sub _constructor_maker_for {
  51   my ($class, $target) = @_;
  52   return unless $MAKERS{$target};
  53   $MAKERS{$target}{constructor} ||= do {
  54     require Method::Generate::Constructor;
  55     Method::Generate::Constructor
  56       ->new(
  57         package => $target,
  58         accessor_generator => do {
  59           require Method::Generate::Accessor;
  60           Method::Generate::Accessor->new;
  61         }
  62       )
  63       ->install_delayed
  64       ->register_attribute_specs(do {
  65         my @spec;
  66         # using the -last- entry in @ISA means that classes created by
  67         # Role::Tiny as N roles + superclass will still get the attributes
  68         # from the superclass
  69         if (my $super = do { no strict 'refs'; ${"${target}::ISA"}[-1] }) {
  70           if (my $con = $MAKERS{$super}{constructor}) {
  71             @spec = %{$con->all_attribute_specs};
  72           }
  73         }
  74         @spec;
  75       });
  76   }
  77 }
  78
  79 1;
  80
  81 =head1 NAME
  82
  83 Moo - Minimalist Object Orientation (with Moose compatiblity)
  84
  85 =head1 WARNING WARNING WARNING
  86
  87 This is a 0.9 release because we're fairly sure it works. For us. Until it's
  88 tested in the wild, we make no guarantees it also works for you.
  89
  90 If this module does something unexpected, please submit a failing test.
  91
  92 But if it eats your cat, sleeps with your boyfriend, or pushes grandma down
  93 the stairs to save her from the terrible secret of space, it's not our fault.
  94
  95 =head1 SYNOPSIS
  96
  97  package Cat::Food;
  98
  99  use Moo;
 100  use Sub::Quote;
 101
 102  sub feed_lion {
 103    my $self = shift;
 104    my $amount = shift || 1;
 105
 106    $self->pounds( $self->pounds - $amount );
 107  }
 108
 109  has taste => (
 110    is => 'ro',
 111  );
 112
 113  has brand => (
 114    is  => 'ro',
 115    isa => sub {
 116      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
 117    },
 118 );
 119
 120  has pounds => (
 121    is  => 'rw',
 122    isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
 123  );
 124
 125  1;
 126
 127 and else where
 128
 129  my $full = Cat::Food->new(
 130     taste  => 'DELICIOUS.',
 131     brand  => 'SWEET-TREATZ',
 132     pounds => 10,
 133  );
 134
 135  $full->feed_lion;
 136
 137  say $full->pounds;
 138
 139 =head1 DESCRIPTION
 140
 141 This module is an extremely light-weight, high-performance L<Moose> replacement.
 142 It also avoids depending on any XS modules to allow simple deployments.  The
 143 name C<Moo> is based on the idea that it provides almost -but not quite- two
 144 thirds of L<Moose>.
 145
 146 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility.  See
 147 L</INCOMPATIBILITIES> for more details.
 148
 149 =head1 IMPORTED METHODS
 150
 151 =head2 new
 152
 153  Foo::Bar->new( attr1 => 3 );
 154
 155 or
 156
 157  Foo::Bar->new({ attr1 => 3 });
 158
 159 =head2 BUILDARGS
 160
 161 This feature from Moose is not yet supported.
 162
 163 =head2 BUILDALL
 164
 165 Don't override (or probably even call) this method.  Instead, you can define
 166 a C<BUILD> method on your class and the constructor will automatically call the
 167 C<BUILD> method from parent down to child after the object has been
 168 instantiated.  Typically this is used for object validation or possibly logging.
 169
 170 =head2 does
 171
 172  if ($foo->does('Some::Role1')) {
 173    ...
 174  }
 175
 176 Returns true if the object composes in the passed role.
 177
 178 =head1 IMPORTED SUBROUTINES
 179
 180 =head2 extends
 181
 182  extends 'Parent::Class';
 183
 184 Declares base class. Multiple superclasses can be passed for multiple
 185 inheritance (but please use roles instead).
 186
 187 Calling extends more than once will REPLACE your superclasses, not add to
 188 them like 'use base' would.
 189
 190 =head2 with
 191
 192  with 'Some::Role1';
 193  with 'Some::Role2';
 194
 195 Composes a L<Role::Tiny> into current class.  Only one role may be composed in
 196 at a time to allow the code to remain as simple as possible.
 197
 198 =head2 has
 199
 200  has attr => (
 201    is => 'ro',
 202  );
 203
 204 Declares an attribute for the class.
 205
 206 The options for C<has> are as follows:
 207
 208 =over 2
 209
 210 =item * is
 211
 212 B<required>, must be C<ro> or C<rw>.  Unsurprisingly, C<ro> generates an
 213 accessor that will not respond to arguments; to be clear: a setter only. C<rw>
 214 will create a perlish getter/setter.
 215
 216 =item * isa
 217
 218 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
 219 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
 220 one should do
 221
 222  isa => quote_sub q{
 223    die "$_[0] is not a number!" unless looks_like_number $_[0]
 224  },
 225
 226 L<Sub::Quote aware|/SUB QUOTE AWARE>
 227
 228 =item * coerce
 229
 230 This Moose feature is not yet supported
 231
 232 =begin hide
 233
 234 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
 235 do something like the following:
 236
 237  coerce => quote_sub q{
 238    $_[0] + 1 unless $_[0] % 2
 239  },
 240
 241 L<Sub::Quote aware|/SUB QUOTE AWARE>
 242
 243 =end hide
 244
 245 =item * trigger
 246
 247 Takes a coderef which will get called any time the attribute is set. Coderef
 248 will be invoked against the object with the new value as an argument.
 249
 250 Note that Moose also passes the old value, if any; this feature is not yet
 251 supported.
 252
 253 L<Sub::Quote aware|/SUB QUOTE AWARE>
 254
 255 =item * default
 256
 257 Takes a coderef which will get called with $self as its only argument
 258 to populate an attribute if no value is supplied to the constructor - or
 259 if the attribute is lazy, when the attribute is first retrieved if no
 260 value has yet been provided.
 261
 262 Note that if your default is fired during new() there is no guarantee that
 263 other attributes have been populated yet so you should not rely on their
 264 existence.
 265
 266 L<Sub::Quote aware|/SUB QUOTE AWARE>
 267
 268 =item * predicate
 269
 270 Takes a method name which will return true if an attribute has a value.
 271
 272 A common example of this would be to call it C<has_$foo>, implying that the
 273 object has a C<$foo> set.
 274
 275 =item * builder
 276
 277 Takes a method name which will be called to create the attribute - functions
 278 exactly like default except that instead of calling
 279
 280   $default->($self);
 281
 282 Moo will call
 283
 284   $self->$builder;
 285
 286 =item * clearer
 287
 288 Takes a method name which will clear the attribute.
 289
 290 =item * lazy
 291
 292 B<Boolean>.  Set this if you want values for the attribute to be grabbed
 293 lazily.  This is usually a good idea if you have a L</builder> which requires
 294 another attribute to be set.
 295
 296 =item * required
 297
 298 B<Boolean>.  Set this if the attribute must be passed on instantiation.
 299
 300 =item * weak_ref
 301
 302 B<Boolean>.  Set this if you want the reference that the attribute contains to
 303 be weakened; use this when circular references are possible, which will cause
 304 leaks.
 305
 306 =item * init_arg
 307
 308 Takes the name of the key to look for at instantiation time of the object.  A
 309 common use of this is to make an underscored attribute have a non-underscored
 310 initialization name. C<undef> means that passing the value in on instantiation
 311
 312 =back
 313
 314 =head2 before
 315
 316  before foo => sub { ... };
 317
 318 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
 319 documentation.
 320
 321 =head2 around
 322
 323  around foo => sub { ... };
 324
 325 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
 326 documentation.
 327
 328 =head2 after
 329
 330  after foo => sub { ... };
 331
 332 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
 333 documentation.
 334
 335 =head1 SUB QUOTE AWARE
 336
 337 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 338 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 339 aware can take advantage of this.
 340
 341 =head1 INCOMPATIBILITIES WITH MOOSE
 342
 343 You can only compose one role at a time.  If your application is large or
 344 complex enough to warrant complex composition, you wanted L<Moose>.
 345
 346 There is no complex type system.  C<isa> is verified with a coderef, if you
 347 need complex types, just make a library of coderefs, or better yet, functions
 348 that return quoted subs.
 349
 350 C<initializer> is not supported in core since the author considers it to be a
 351 bad idea but may be supported by an extension in future.
 352
 353 There is no meta object.  If you need this level of complexity you wanted
 354 L<Moose> - Moo succeeds at being small because it explicitly does not
 355 provide a metaprotocol.
 356
 357 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
 358 be handled by around albeit with a little more typing, and the author considers
 359 augment to be a bad idea.
 360
 361 L</default> only supports coderefs, because doing otherwise is usually a
 362 mistake anyway.
 363
 364 C<lazy_build> is not supported per se, but of course it will work if you
 365 manually set all the options it implies.
 366
 367 C<auto_deref> is not supported since the author considers it a bad idea.
 368
 369 C<documentation> is not supported since it's a very poor replacement for POD.