foo
[gitmo/Moose.git] / lib / Moose.pm
CommitLineData
fcd84ca9 1
2package Moose;
3
4use strict;
5use warnings;
6
2d562421 7our $VERSION = '0.05';
fcd84ca9 8
cc65ead0 9use Scalar::Util 'blessed', 'reftype';
fcd84ca9 10use Carp 'confess';
bc1e29b5 11use Sub::Name 'subname';
fcd84ca9 12
7f18097c 13use UNIVERSAL::require;
2d562421 14use Sub::Exporter;
7f18097c 15
ef1d5f4b 16use Class::MOP;
17
c0e30cf5 18use Moose::Meta::Class;
7415b2cb 19use Moose::Meta::TypeConstraint;
7c13858b 20use Moose::Meta::TypeCoercion;
78cd1d3b 21use Moose::Meta::Attribute;
ddd0ec20 22use Moose::Meta::Instance;
c0e30cf5 23
fcd84ca9 24use Moose::Object;
7415b2cb 25use Moose::Util::TypeConstraints;
a15dff8d 26
a3c7e2fe 27{
28 my ( $CALLER, %METAS );
29
2d562421 30 sub _find_meta {
a3c7e2fe 31 my $class = $CALLER;
32
33 return $METAS{$class} if exists $METAS{$class};
34
35 # make a subtype for each Moose class
36 subtype $class
37 => as 'Object'
38 => where { $_->isa($class) }
39 unless find_type_constraint($class);
40
41 my $meta;
42 if ($class->can('meta')) {
43 $meta = $class->meta();
44 (blessed($meta) && $meta->isa('Moose::Meta::Class'))
45 || confess "Whoops, not møøsey enough";
46 }
47 else {
590868a3 48 $meta = Moose::Meta::Class->initialize($class);
a3c7e2fe 49 $meta->add_method('meta' => sub {
50 # re-initialize so it inherits properly
fcb7afc2 51 Moose::Meta::Class->initialize(blessed($_[0]) || $_[0]);
a3c7e2fe 52 })
53 }
54
55 # make sure they inherit from Moose::Object
56 $meta->superclasses('Moose::Object')
57 unless $meta->superclasses();
58
59 return $METAS{$class} = $meta;
60 }
61
62 my %exports = (
63 extends => sub {
2d562421 64 my $meta = _find_meta();
3d544ed5 65 return subname 'Moose::extends' => sub {
a3c7e2fe 66 _load_all_classes(@_);
67 $meta->superclasses(@_)
68 };
69 },
70 with => sub {
2d562421 71 my $meta = _find_meta();
3d544ed5 72 return subname 'Moose::with' => sub {
a3c7e2fe 73 my ($role) = @_;
74 _load_all_classes($role);
75 $role->meta->apply($meta);
76 };
77 },
78 has => sub {
2d562421 79 my $meta = _find_meta();
3d544ed5 80 return subname 'Moose::has' => sub {
a3c7e2fe 81 my ($name, %options) = @_;
2d2b92e5 82 if ($name =~ /^\+(.*)/) {
1d768fb1 83 my $inherited_attr = $meta->find_attribute_by_name($1);
84 (defined $inherited_attr)
85 || confess "Could not find an attribute by the name of '$1' to inherit from";
ce0e8d63 86 my $new_attr = $inherited_attr->clone_and_inherit_options(%options);
1d768fb1 87 $meta->add_attribute($new_attr);
b0ea39ef 88 }
89 else {
2d2b92e5 90 if ($options{metaclass}) {
91 _load_all_classes($options{metaclass});
92 $meta->add_attribute($options{metaclass}->new($name, %options));
93 }
94 else {
95 $meta->add_attribute($name, %options);
96 }
b0ea39ef 97 }
a3c7e2fe 98 };
99 },
100 before => sub {
2d562421 101 my $meta = _find_meta();
3d544ed5 102 return subname 'Moose::before' => sub {
a3c7e2fe 103 my $code = pop @_;
104 $meta->add_before_method_modifier($_, $code) for @_;
105 };
106 },
107 after => sub {
2d562421 108 my $meta = _find_meta();
3d544ed5 109 return subname 'Moose::after' => sub {
a3c7e2fe 110 my $code = pop @_;
111 $meta->add_after_method_modifier($_, $code) for @_;
112 };
113 },
114 around => sub {
2d562421 115 my $meta = _find_meta();
3d544ed5 116 return subname 'Moose::around' => sub {
a3c7e2fe 117 my $code = pop @_;
118 $meta->add_around_method_modifier($_, $code) for @_;
119 };
120 },
121 super => sub {
2d562421 122 my $meta = _find_meta();
3d544ed5 123 return subname 'Moose::super' => sub {};
a3c7e2fe 124 },
125 override => sub {
2d562421 126 my $meta = _find_meta();
3d544ed5 127 return subname 'Moose::override' => sub {
a3c7e2fe 128 my ($name, $method) = @_;
129 $meta->add_override_method_modifier($name => $method);
130 };
131 },
132 inner => sub {
2d562421 133 my $meta = _find_meta();
3d544ed5 134 return subname 'Moose::inner' => sub {};
a3c7e2fe 135 },
136 augment => sub {
2d562421 137 my $meta = _find_meta();
3d544ed5 138 return subname 'Moose::augment' => sub {
a3c7e2fe 139 my ($name, $method) = @_;
140 $meta->add_augment_method_modifier($name => $method);
141 };
142 },
143 confess => sub {
144 return \&Carp::confess;
145 },
146 blessed => sub {
147 return \&Scalar::Util::blessed;
54b1cdf0 148 },
149 all_methods => sub {
065b95d5 150 subname 'Moose::all_methods' => sub () {
54b1cdf0 151 sub {
152 my ( $class, $delegate_class ) = @_;
153 $delegate_class->compute_all_applicable_methods();
154 }
155 }
a3c7e2fe 156 }
157 );
3d544ed5 158
a3c7e2fe 159 my $exporter = Sub::Exporter::build_exporter({
160 exports => \%exports,
161 groups => {
162 default => [':all']
163 }
164 });
165
fcb7afc2 166 sub import {
a3c7e2fe 167 $CALLER = caller();
168
169 # we should never export to main
170 return if $CALLER eq 'main';
171
172 goto $exporter;
fcb7afc2 173 }
fcd84ca9 174}
175
e9bb8a31 176## Utility functions
177
78cd1d3b 178sub _load_all_classes {
e9bb8a31 179 foreach my $super (@_) {
180 # see if this is already
181 # loaded in the symbol table
182 next if _is_class_already_loaded($super);
183 # otherwise require it ...
184 ($super->require)
185 || confess "Could not load superclass '$super' because : " . $UNIVERSAL::require::ERROR;
186 }
187}
188
d7f17ebb 189sub _is_class_already_loaded {
190 my $name = shift;
191 no strict 'refs';
192 return 1 if defined ${"${name}::VERSION"} || defined @{"${name}::ISA"};
193 foreach (keys %{"${name}::"}) {
194 next if substr($_, -2, 2) eq '::';
195 return 1 if defined &{"${name}::$_"};
196 }
197 return 0;
198}
199
fcd84ca9 2001;
201
202__END__
203
204=pod
205
206=head1 NAME
207
e522431d 208Moose - Moose, it's the new Camel
fcd84ca9 209
210=head1 SYNOPSIS
e522431d 211
212 package Point;
213 use Moose;
214
182134e8 215 has 'x' => (isa => 'Int', is => 'rw');
216 has 'y' => (isa => 'Int', is => 'rw');
e522431d 217
218 sub clear {
219 my $self = shift;
220 $self->x(0);
221 $self->y(0);
222 }
223
224 package Point3D;
225 use Moose;
226
227 extends 'Point';
09fdc1dc 228
182134e8 229 has 'z' => (isa => 'Int');
e522431d 230
231 after 'clear' => sub {
232 my $self = shift;
233 $self->{z} = 0;
234 };
235
236=head1 CAVEAT
237
79592a54 238This is an early release of this module, it still needs
e522431d 239some fine tuning and B<lots> more documentation. I am adopting
240the I<release early and release often> approach with this module,
241so keep an eye on your favorite CPAN mirror!
242
fcd84ca9 243=head1 DESCRIPTION
244
e522431d 245Moose is an extension of the Perl 5 object system.
246
247=head2 Another object system!?!?
fcd84ca9 248
e522431d 249Yes, I know there has been an explosion recently of new ways to
250build object's in Perl 5, most of them based on inside-out objects,
251and other such things. Moose is different because it is not a new
252object system for Perl 5, but instead an extension of the existing
253object system.
3c7278fb 254
e522431d 255Moose is built on top of L<Class::MOP>, which is a metaclass system
256for Perl 5. This means that Moose not only makes building normal
505c6fac 257Perl 5 objects better, but it also provides the power of metaclass
258programming.
e522431d 259
260=head2 What does Moose stand for??
261
262Moose doesn't stand for one thing in particular, however, if you
263want, here are a few of my favorites, feel free to contribute
264more :)
265
266=over 4
267
5569c072 268=item Make Other Object Systems Envious
e522431d 269
270=item Makes Object Orientation So Easy
271
5569c072 272=item Makes Object Orientation Spiffy- Er (sorry ingy)
505c6fac 273
5569c072 274=item Most Other Object Systems Emasculate
505c6fac 275
276=item My Overcraft Overfilled (with) Some Eels
277
278=item Moose Often Ovulate Sorta Early
279
505c6fac 280=item Many Overloaded Object Systems Exists
281
282=item Moose Offers Often Super Extensions
283
446e850f 284=item Meta Object Orientation Syntax Extensions
285
e522431d 286=back
3c7278fb 287
6ba6d68c 288=head1 BUILDING CLASSES WITH MOOSE
289
290Moose makes every attempt to provide as much convience during class
291construction/definition, but still stay out of your way if you want
292it to. Here are some of the features Moose provides:
293
294Unless specified with C<extends>, any class which uses Moose will
295inherit from L<Moose::Object>.
296
297Moose will also manage all attributes (including inherited ones) that
298are defined with C<has>. And assuming that you call C<new> which is
299inherited from L<Moose::Object>, then this includes properly initializing
300all instance slots, setting defaults where approprtiate and performing any
301type constraint checking or coercion.
302
79592a54 303For more details, see the ever expanding L<Moose::Cookbook>.
304
6ba6d68c 305=head1 EXPORTED FUNCTIONS
306
307Moose will export a number of functions into the class's namespace, which
308can then be used to set up the class. These functions all work directly
309on the current class.
310
311=over 4
312
313=item B<meta>
314
315This is a method which provides access to the current class's metaclass.
316
317=item B<extends (@superclasses)>
318
319This function will set the superclass(es) for the current class.
320
321This approach is recommended instead of C<use base>, because C<use base>
322actually C<push>es onto the class's C<@ISA>, whereas C<extends> will
323replace it. This is important to ensure that classes which do not have
324superclasses properly inherit from L<Moose::Object>.
325
e9ec68d6 326=item B<with ($role)>
327
76d37e5a 328This will apply a given C<$role> to the local class. Role support is
329currently very experimental, see L<Moose::Role> for more details.
e9ec68d6 330
6ba6d68c 331=item B<has ($name, %options)>
332
333This will install an attribute of a given C<$name> into the current class.
334The list of C<%options> are the same as those provided by both
335L<Class::MOP::Attribute> and L<Moose::Meta::Attribute>, in addition to a
336few convience ones provided by Moose which are listed below:
337
338=over 4
339
076c81ed 340=item I<is =E<gt> 'rw'|'ro'>
6ba6d68c 341
342The I<is> option accepts either I<rw> (for read/write) or I<ro> (for read
343only). These will create either a read/write accessor or a read-only
344accessor respectively, using the same name as the C<$name> of the attribute.
345
346If you need more control over how your accessors are named, you can use the
347I<reader>, I<writer> and I<accessor> options inherited from L<Moose::Meta::Attribute>.
348
076c81ed 349=item I<isa =E<gt> $type_name>
6ba6d68c 350
351The I<isa> option uses Moose's type constraint facilities to set up runtime
352type checking for this attribute. Moose will perform the checks during class
353construction, and within any accessors. The C<$type_name> argument must be a
354string. The string can be either a class name, or a type defined using
355Moose's type defintion features.
356
daea75c9 357=item I<coerce =E<gt> (1|0)>
358
359This will attempt to use coercion with the supplied type constraint to change
360the value passed into any accessors of constructors. You B<must> have supplied
361a type constraint in order for this to work. See L<Moose::Cookbook::Recipe5>
362for an example usage.
363
364=item I<does =E<gt> $role_name>
365
366This will accept the name of a role which the value stored in this attribute
367is expected to have consumed.
368
369=item I<required =E<gt> (1|0)>
370
371This marks the attribute as being required. This means a value must be supplied
372during class construction, and the attribute can never be set to C<undef> with
373an accessor.
374
375=item I<weak_ref =E<gt> (1|0)>
376
377This will tell the class to strore the value of this attribute as a weakened
378reference. If an attribute is a weakened reference, it can B<not> also be coerced.
379
380=item I<lazy =E<gt> (1|0)>
381
382This will tell the class to not create this slot until absolutely nessecary.
383If an attribute is marked as lazy it B<must> have a default supplied.
384
385=item I<trigger =E<gt> $code>
386
387The trigger option is a CODE reference which will be called after the value of
388the attribute is set. The CODE ref will be passed the instance itself, the
389updated value and the attribute meta-object (this is for more advanced fiddling
cce8198b 390and can typically be ignored in most cases). You can B<not> have a trigger on
391a read-only attribute.
daea75c9 392
6ba6d68c 393=back
394
076c81ed 395=item B<before $name|@names =E<gt> sub { ... }>
6ba6d68c 396
076c81ed 397=item B<after $name|@names =E<gt> sub { ... }>
6ba6d68c 398
076c81ed 399=item B<around $name|@names =E<gt> sub { ... }>
6ba6d68c 400
401This three items are syntactic sugar for the before, after and around method
402modifier features that L<Class::MOP> provides. More information on these can
403be found in the L<Class::MOP> documentation for now.
404
159da176 405=item B<super>
406
407The keyword C<super> is a noop when called outside of an C<override> method. In
408the context of an C<override> method, it will call the next most appropriate
409superclass method with the same arguments as the original method.
410
411=item B<override ($name, &sub)>
412
413An C<override> method, is a way of explictly saying "I am overriding this
414method from my superclass". You can call C<super> within this method, and
415it will work as expected. The same thing I<can> be accomplished with a normal
416method call and the C<SUPER::> pseudo-package, it is really your choice.
417
418=item B<inner>
419
420The keyword C<inner>, much like C<super>, is a no-op outside of the context of
421an C<augment> method. You can think of C<inner> as being the inverse of
422C<super>, the details of how C<inner> and C<augment> work is best described in
423the L<Moose::Cookbook>.
424
425=item B<augment ($name, &sub)>
426
427An C<augment> method, is a way of explictly saying "I am augmenting this
428method from my superclass". Once again, the details of how C<inner> and
429C<augment> work is best described in the L<Moose::Cookbook>.
430
6ba6d68c 431=item B<confess>
432
433This is the C<Carp::confess> function, and exported here beause I use it
434all the time. This feature may change in the future, so you have been warned.
435
436=item B<blessed>
437
438This is the C<Scalar::Uti::blessed> function, it is exported here beause I
439use it all the time. It is highly recommended that this is used instead of
440C<ref> anywhere you need to test for an object's class name.
441
442=back
443
05d9eaf6 444=head1 CAVEATS
445
446=over 4
447
448=item *
449
450It should be noted that C<super> and C<inner> can B<not> be used in the same
451method. However, they can be combined together with the same class hierarchy,
452see F<t/014_override_augment_inner_super.t> for an example.
453
454The reason that this is so is because C<super> is only valid within a method
455with the C<override> modifier, and C<inner> will never be valid within an
456C<override> method. In fact, C<augment> will skip over any C<override> methods
457when searching for it's appropriate C<inner>.
458
459This might seem like a restriction, but I am of the opinion that keeping these
460two features seperate (but interoperable) actually makes them easy to use since
461their behavior is then easier to predict. Time will tell if I am right or not.
462
463=back
464
5569c072 465=head1 ACKNOWLEDGEMENTS
466
467=over 4
468
54c189df 469=item I blame Sam Vilain for introducing me to the insanity that is meta-models.
5569c072 470
54c189df 471=item I blame Audrey Tang for then encouraging my meta-model habit in #perl6.
5569c072 472
076c81ed 473=item Without Yuval "nothingmuch" Kogman this module would not be possible,
54c189df 474and it certainly wouldn't have this name ;P
5569c072 475
476=item The basis of the TypeContraints module was Rob Kinyon's idea
477originally, I just ran with it.
478
076c81ed 479=item Thanks to mst & chansen and the whole #moose poose for all the
d46a48f3 480ideas/feature-requests/encouragement
481
5569c072 482=back
483
e90c03d0 484=head1 SEE ALSO
485
486=over 4
487
6ba6d68c 488=item L<Class::MOP> documentation
489
490=item The #moose channel on irc.perl.org
491
e90c03d0 492=item L<http://forum2.org/moose/>
493
159da176 494=item L<http://www.cs.utah.edu/plt/publications/oopsla04-gff.pdf>
495
496This paper (suggested by lbr on #moose) was what lead to the implementation
497of the C<super>/C<overrride> and C<inner>/C<augment> features. If you really
498want to understand this feature, I suggest you read this.
499
e90c03d0 500=back
501
fcd84ca9 502=head1 BUGS
503
504All complex software has bugs lurking in it, and this module is no
505exception. If you find a bug please either email me, or add the bug
506to cpan-RT.
507
fcd84ca9 508=head1 AUTHOR
509
510Stevan Little E<lt>stevan@iinteractive.comE<gt>
511
512=head1 COPYRIGHT AND LICENSE
513
514Copyright 2006 by Infinity Interactive, Inc.
515
516L<http://www.iinteractive.com>
517
518This library is free software; you can redistribute it and/or modify
519it under the same terms as Perl itself.
520
ddd0ec20 521=cut