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