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