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