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