split authority hackery out into Moo::sification
[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.009014'; # 0.9.13
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. Coderef
329 will be invoked against the object with the new value as an argument.
330
331 Note that Moose also passes the old value, if any; this feature is not yet
332 supported.
333
334 L<Sub::Quote aware|/SUB QUOTE AWARE>
335
336 =item * default
337
338 Takes a coderef which will get called with $self as its only argument
339 to populate an attribute if no value is supplied to the constructor - or
340 if the attribute is lazy, when the attribute is first retrieved if no
341 value has yet been provided.
342
343 Note that if your default is fired during new() there is no guarantee that
344 other attributes have been populated yet so you should not rely on their
345 existence.
346
347 L<Sub::Quote aware|/SUB QUOTE AWARE>
348
349 =item * predicate
350
351 Takes a method name which will return true if an attribute has a value.
352
353 A common example of this would be to call it C<has_$foo>, implying that the
354 object has a C<$foo> set.
355
356 =item * builder
357
358 Takes a method name which will be called to create the attribute - functions
359 exactly like default except that instead of calling
360
361   $default->($self);
362
363 Moo will call
364
365   $self->$builder;
366
367 =item * clearer
368
369 Takes a method name which will clear the attribute.
370
371 =item * lazy
372
373 B<Boolean>.  Set this if you want values for the attribute to be grabbed
374 lazily.  This is usually a good idea if you have a L</builder> which requires
375 another attribute to be set.
376
377 =item * required
378
379 B<Boolean>.  Set this if the attribute must be passed on instantiation.
380
381 =item * reader
382
383 The value of this attribute will be the name of the method to get the value of
384 the attribute.  If you like Java style methods, you might set this to
385 C<get_foo>
386
387 =item * writer
388
389 The value of this attribute will be the name of the method to set the value of
390 the attribute.  If you like Java style methods, you might set this to
391 C<set_foo>
392
393 =item * weak_ref
394
395 B<Boolean>.  Set this if you want the reference that the attribute contains to
396 be weakened; use this when circular references are possible, which will cause
397 leaks.
398
399 =item * init_arg
400
401 Takes the name of the key to look for at instantiation time of the object.  A
402 common use of this is to make an underscored attribute have a non-underscored
403 initialization name. C<undef> means that passing the value in on instantiation
404
405 =back
406
407 =head2 before
408
409  before foo => sub { ... };
410
411 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
412 documentation.
413
414 =head2 around
415
416  around foo => sub { ... };
417
418 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
419 documentation.
420
421 =head2 after
422
423  after foo => sub { ... };
424
425 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
426 documentation.
427
428 =head1 SUB QUOTE AWARE
429
430 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
431 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
432 aware can take advantage of this.
433
434 =head1 INCOMPATIBILITIES WITH MOOSE
435
436 You can only compose one role at a time.  If your application is large or
437 complex enough to warrant complex composition, you wanted L<Moose>.  Note that
438 this does not mean you can only compose one role per class -
439
440   with 'FirstRole';
441   with 'SecondRole';
442
443 is absolutely fine, there's just currently no equivalent of Moose's
444
445   with 'FirstRole', 'SecondRole';
446
447 which composes the two roles together, and then applies them.
448
449 There is no built in type system.  C<isa> is verified with a coderef, if you
450 need complex types, just make a library of coderefs, or better yet, functions
451 that return quoted subs. L<MooX::Types::MooseLike> provides a similar API
452 to L<MooseX::Types::Moose> so that you can write
453
454   has days_to_live => (is => 'ro', isa => Int);
455
456 and have it work with both; it is hoped that providing only subrefs as an
457 API will encourage the use of other type systems as well, since it's
458 probably the weakest part of Moose design-wise.
459
460 C<initializer> is not supported in core since the author considers it to be a
461 bad idea but may be supported by an extension in future.
462
463 There is no meta object.  If you need this level of complexity you wanted
464 L<Moose> - Moo succeeds at being small because it explicitly does not
465 provide a metaprotocol.
466
467 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
468 be handled by around albeit with a little more typing, and the author considers
469 augment to be a bad idea.
470
471 The C<dump> method is not provided by default. The author suggests loading 
472 L<Devel::Dwarn> into C<main::> (via C<perl -MDevel::Dwarn ...> for example) and
473 using C<$obj-E<gt>$::Dwarn()> instead.
474
475 L</default> only supports coderefs, because doing otherwise is usually a
476 mistake anyway.
477
478 C<lazy_build> is not supported per se, but of course it will work if you
479 manually set all the options it implies.
480
481 C<auto_deref> is not supported since the author considers it a bad idea.
482
483 C<documentation> is not supported since it's a very poor replacement for POD.
484
485 Handling of warnings: when you C<use Moo> we enable FATAL warnings.  The nearest
486 similar invocation for L<Moose> would be:
487
488   use Moose;
489   use warnings FATAL => "all";
490
491 Additionally, L<Moo> supports a set of attribute option shortcuts intended to
492 reduce common boilerplate.  The set of shortcuts is the same as in the L<Moose>
493 module L<MooseX::AttributeShortcuts>.  So if you:
494
495     package MyClass;
496     use Moo;
497
498 The nearest L<Moose> invocation would be:
499
500     package MyClass;
501
502     use Moose;
503     use warnings FATAL => "all";
504     use MooseX::AttributeShortcuts;
505
506 or, if you're inheriting from a non-Moose class,
507
508     package MyClass;
509
510     use Moose;
511     use MooseX::NonMoose;
512     use warnings FATAL => "all";
513     use MooseX::AttributeShortcuts;
514
515 Finally, Moose requires you to call
516
517     __PACKAGE__->meta->make_immutable;
518
519 at the end of your class to get an inlined (i.e. not horribly slow)
520 constructor. Moo does it automatically the first time ->new is called
521 on your class.
522
523 =head1 AUTHOR
524
525 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
526
527 =head1 CONTRIBUTORS
528
529 dg - David Leadbeater (cpan:DGL) <dgl@dgl.cx>
530
531 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
532
533 hobbs - Andrew Rodland (cpan:ARODLAND) <arodland@cpan.org>
534
535 jnap - John Napiorkowski (cpan:JJNAPIORK) <jjn1056@yahoo.com>
536
537 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
538
539 chip - Chip Salzenberg (cpan:CHIPS) <chip@pobox.com>
540
541 ajgb - Alex J. G. BurzyƄski (cpan:AJGB) <ajgb@cpan.org>
542
543 doy - Jesse Luehrs (cpan:DOY) <doy at tozt dot net>
544
545 perigrin - Chris Prather (cpan:PERIGRIN) <chris@prather.org>
546
547 =head1 COPYRIGHT
548
549 Copyright (c) 2010-2011 the Moo L</AUTHOR> and L</CONTRIBUTORS>
550 as listed above.
551
552 =head1 LICENSE
553
554 This library is free software and may be distributed under the same terms
555 as perl itself.
556
557 =cut