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