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($_[0], $target);
  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 =pod
  81
  82 =head1 SYNOPSIS
  83
  84  package Cat::Food;
  85
  86  use Moo;
  87  use Sub::Quote;
  88
  89  sub feed_lion {
  90    my $self = shift;
  91    my $amount = shift || 1;
  92
  93    $self->pounds( $self->pounds - $amount );
  94  }
  95
  96  has taste => (
  97    is => 'ro',
  98  );
  99
 100  has brand => (
 101    is  => 'ro',
 102    isa => sub {
 103      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
 104    },
 105 );
 106
 107  has pounds => (
 108    is  => 'rw',
 109    isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
 110  );
 111
 112  1;
 113
 114 and else where
 115
 116  my $full = Cat::Food->new(
 117     taste  => 'DELICIOUS.',
 118     brand  => 'SWEET-TREATZ',
 119     pounds => 10,
 120  );
 121
 122  $full->feed_lion;
 123
 124  say $full->pounds;
 125
 126 =head1 DESCRIPTION
 127
 128 This module is an extremely light-weight, high-performance L<Moose> replacement.
 129 It also avoids depending on any XS modules to allow simple deployments.  The
 130 name C<Moo> is based on the idea that it provides almost -but not quite- two
 131 thirds of L<Moose>.
 132
 133 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility.  See
 134 L</INCOMPATIBILITIES> for more details.
 135
 136 =head1 IMPORTED METHODS
 137
 138 =head2 new
 139
 140  Foo::Bar->new( attr1 => 3 );
 141
 142 or
 143
 144  Foo::Bar->new({ attr1 => 3 });
 145
 146 =head2 BUILDALL
 147
 148 Don't override (or probably even call) this method.  Instead, you can define
 149 a C<BUILD> method on your class and the constructor will automatically call the
 150 C<BUILD> method from parent down to child after the object has been
 151 instantiated.  Typically this is used for object validation or possibly logging.
 152
 153 =head2 does
 154
 155  if ($foo->does('Some::Role1')) {
 156    ...
 157  }
 158
 159 Returns true if the object composes in the passed role.
 160
 161 =head1 IMPORTED SUBROUTINES
 162
 163 =head2 extends
 164
 165  extends 'Parent::Class';
 166
 167 Declares base class
 168
 169 =head2 with
 170
 171  with 'Some::Role1';
 172  with 'Some::Role2';
 173
 174 Composes a L<Role::Tiny> into current class.  Only one role may be composed in
 175 at a time to allow the code to remain as simple as possible.
 176
 177 =head2 has
 178
 179  has attr => (
 180    is => 'ro',
 181  );
 182
 183 Declares an attribute for the class.
 184
 185 The options for C<has> are as follows:
 186
 187 =over 2
 188
 189 =item * is
 190
 191 B<required>, must be C<ro> or C<rw>.  Unsurprisingly, C<ro> generates an
 192 accessor that will not respond to arguments; to be clear: a setter only. C<rw>
 193 will create a perlish getter/setter.
 194
 195 =item * isa
 196
 197 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
 198 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
 199 one should do
 200
 201  isa => quote_sub q{
 202    die "$_[0] is not a number!" unless looks_like_number $_[0]
 203  },
 204
 205 L<Sub::Quote aware|/SUB QUOTE AWARE>
 206
 207 =item * coerce
 208
 209 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
 210 do something like the following:
 211
 212  coerce => quote_sub q{
 213    $_[0] + 1 unless $_[0] % 2
 214  },
 215
 216 L<Sub::Quote aware|/SUB QUOTE AWARE>
 217
 218 =item * trigger
 219
 220 Takes a coderef which will get called any time the attribute is set. Coderef
 221 will be invoked against the object with the new value as an argument.
 222
 223 L<Sub::Quote aware|/SUB QUOTE AWARE>
 224
 225 =item * default
 226
 227 Takes a coderef which will get called to populate an attribute.
 228
 229 L<Sub::Quote aware|/SUB QUOTE AWARE>
 230
 231 =item * predicate
 232
 233 Takes a method name which will return true if an attribute has been set.
 234
 235 A common example of this would be to call it C<has_$foo>, implying that the
 236 object has a C<$foo> set.
 237
 238 =item * builder
 239
 240 Takes a method name which will be called to create the attribute.
 241
 242 =item * clearer
 243
 244 Takes a method name which will clear the attribute.
 245
 246 =item * lazy
 247
 248 B<Boolean>.  Set this if you want values for the attribute to be grabbed
 249 lazily.  This is usually a good idea if you have a L</builder> which requires
 250 another attribute to be set.
 251
 252 =item * required
 253
 254 B<Boolean>.  Set this if the attribute must be passed on instantiation.
 255
 256 =item * weak_ref
 257
 258 B<Boolean>.  Set this if you want the reference that the attribute contains to
 259 be weakened; use this when circular references are possible, which will cause
 260 leaks.
 261
 262 =item * init_arg
 263
 264 Takes the name of the key to look for at instantiation time of the object.  A
 265 common use of this is to make an underscored attribute have a non-underscored
 266 initialization name. C<undef> means that passing the value in on instantiation
 267
 268 =back
 269
 270 =head2 before
 271
 272  before foo => sub { ... };
 273
 274 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
 275 documentation.
 276
 277 =head2 around
 278
 279  around foo => sub { ... };
 280
 281 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
 282 documentation.
 283
 284 =head2 after
 285
 286  after foo => sub { ... };
 287
 288 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
 289 documentation.
 290
 291
 292 =head1 SUB QUOTE AWARE
 293
 294 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 295 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 296 aware can take advantage of this.
 297
 298 =head1 INCOMPATIBILITIES
 299
 300 You can only compose one role at a time.  If your application is large or
 301 complex enough to warrant complex composition, you wanted L<Moose>.
 302
 303 There is no complex type system.  C<isa> is verified with a coderef, if you
 304 need complex types, just make a library of coderefs, or better yet, functions
 305 that return quoted subs.
 306
 307 C<initializer> is not supported in core, but with an extension it is supported.
 308
 309 There is no meta object.  If you need this level of complexity you wanted
 310 L<Moose>.
 311
 312 No support for C<super>, C<override>, C<inner>, or C<augment>.
 313
 314 L</default> only supports coderefs, because doing otherwise is usually a
 315 mistake anyway.
 316
 317 C<lazy_build> is not supported per se, but of course it will work if you
 318 manually set all the options it implies.
 319
 320 C<auto_deref> is not supported.
 321
 322 C<documentation> is not supported.