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