Moose::Object->dump, cause I am sick of manually loading Data::Dumper all the time
[gitmo/Moose.git] / lib / Moose.pm
CommitLineData
fcd84ca9 1
2package Moose;
3
4use strict;
5use warnings;
6
2bdd01cd 7our $VERSION = '0.12';
fcd84ca9 8
cc65ead0 9use Scalar::Util 'blessed', 'reftype';
fcd84ca9 10use Carp 'confess';
bc1e29b5 11use Sub::Name 'subname';
31f8ec72 12use B 'svref_2object';
fcd84ca9 13
7f18097c 14use UNIVERSAL::require;
2d562421 15use Sub::Exporter;
7f18097c 16
ef1d5f4b 17use Class::MOP;
18
c0e30cf5 19use Moose::Meta::Class;
7415b2cb 20use Moose::Meta::TypeConstraint;
7c13858b 21use Moose::Meta::TypeCoercion;
78cd1d3b 22use Moose::Meta::Attribute;
ddd0ec20 23use Moose::Meta::Instance;
c0e30cf5 24
fcd84ca9 25use Moose::Object;
7415b2cb 26use Moose::Util::TypeConstraints;
a15dff8d 27
a3c7e2fe 28{
be33e4f3 29 my $CALLER;
a3c7e2fe 30
be33e4f3 31 sub _init_meta {
a3c7e2fe 32 my $class = $CALLER;
33
a3c7e2fe 34 # make a subtype for each Moose class
35 subtype $class
36 => as 'Object'
37 => where { $_->isa($class) }
38 unless find_type_constraint($class);
39
40 my $meta;
41 if ($class->can('meta')) {
fcec2383 42 # NOTE:
43 # this is the case where the metaclass pragma
44 # was used before the 'use Moose' statement to
45 # override a specific class
a3c7e2fe 46 $meta = $class->meta();
47 (blessed($meta) && $meta->isa('Moose::Meta::Class'))
48 || confess "Whoops, not møøsey enough";
49 }
50 else {
fcec2383 51 # NOTE:
52 # this is broken currently, we actually need
53 # to allow the possiblity of an inherited
54 # meta, which will not be visible until the
55 # user 'extends' first. This needs to have
56 # more intelligence to it
590868a3 57 $meta = Moose::Meta::Class->initialize($class);
a3c7e2fe 58 $meta->add_method('meta' => sub {
59 # re-initialize so it inherits properly
fcb7afc2 60 Moose::Meta::Class->initialize(blessed($_[0]) || $_[0]);
a3c7e2fe 61 })
62 }
63
64 # make sure they inherit from Moose::Object
65 $meta->superclasses('Moose::Object')
66 unless $meta->superclasses();
a3c7e2fe 67 }
68
69 my %exports = (
70 extends => sub {
be33e4f3 71 my $class = $CALLER;
68117c45 72 return subname 'Moose::extends' => sub (@) {
73 confess "Must derive at least one class" unless @_;
a3c7e2fe 74 _load_all_classes(@_);
1341f10c 75 # this checks the metaclass to make sure
76 # it is correct, sometimes it can get out
77 # of sync when the classes are being built
78 my $meta = $class->meta->_fix_metaclass_incompatability(@_);
be33e4f3 79 $meta->superclasses(@_);
a3c7e2fe 80 };
81 },
82 with => sub {
be33e4f3 83 my $class = $CALLER;
68117c45 84 return subname 'Moose::with' => sub (@) {
db1ab48d 85 my (@roles) = @_;
68117c45 86 confess "Must specify at least one role" unless @roles;
db1ab48d 87 _load_all_classes(@roles);
1341f10c 88 $class->meta->_apply_all_roles(@roles);
a3c7e2fe 89 };
90 },
91 has => sub {
be33e4f3 92 my $class = $CALLER;
2c0cbef7 93 return subname 'Moose::has' => sub ($;%) {
452bac1b 94 my ($name, %options) = @_;
1341f10c 95 $class->meta->_process_attribute($name, %options);
a3c7e2fe 96 };
97 },
98 before => sub {
be33e4f3 99 my $class = $CALLER;
2c0cbef7 100 return subname 'Moose::before' => sub (@&) {
a3c7e2fe 101 my $code = pop @_;
be33e4f3 102 my $meta = $class->meta;
a3c7e2fe 103 $meta->add_before_method_modifier($_, $code) for @_;
104 };
105 },
106 after => sub {
be33e4f3 107 my $class = $CALLER;
2c0cbef7 108 return subname 'Moose::after' => sub (@&) {
a3c7e2fe 109 my $code = pop @_;
be33e4f3 110 my $meta = $class->meta;
a3c7e2fe 111 $meta->add_after_method_modifier($_, $code) for @_;
112 };
113 },
114 around => sub {
be33e4f3 115 my $class = $CALLER;
2c0cbef7 116 return subname 'Moose::around' => sub (@&) {
a3c7e2fe 117 my $code = pop @_;
be33e4f3 118 my $meta = $class->meta;
a3c7e2fe 119 $meta->add_around_method_modifier($_, $code) for @_;
120 };
121 },
122 super => sub {
3d544ed5 123 return subname 'Moose::super' => sub {};
a3c7e2fe 124 },
125 override => sub {
be33e4f3 126 my $class = $CALLER;
2c0cbef7 127 return subname 'Moose::override' => sub ($&) {
a3c7e2fe 128 my ($name, $method) = @_;
be33e4f3 129 $class->meta->add_override_method_modifier($name => $method);
a3c7e2fe 130 };
131 },
132 inner => sub {
3d544ed5 133 return subname 'Moose::inner' => sub {};
a3c7e2fe 134 },
135 augment => sub {
be33e4f3 136 my $class = $CALLER;
2c0cbef7 137 return subname 'Moose::augment' => sub (@&) {
a3c7e2fe 138 my ($name, $method) = @_;
be33e4f3 139 $class->meta->add_augment_method_modifier($name => $method);
a3c7e2fe 140 };
141 },
142 confess => sub {
143 return \&Carp::confess;
144 },
145 blessed => sub {
146 return \&Scalar::Util::blessed;
147 }
148 );
3d544ed5 149
a3c7e2fe 150 my $exporter = Sub::Exporter::build_exporter({
151 exports => \%exports,
152 groups => {
153 default => [':all']
154 }
155 });
156
fcb7afc2 157 sub import {
a3c7e2fe 158 $CALLER = caller();
c235cd98 159
160 strict->import;
161 warnings->import;
a3c7e2fe 162
163 # we should never export to main
164 return if $CALLER eq 'main';
be33e4f3 165
166 _init_meta();
9eacbf7c 167
a3c7e2fe 168 goto $exporter;
fcb7afc2 169 }
31f8ec72 170
171 sub unimport {
172 no strict 'refs';
173 my $class = caller();
174 # loop through the exports ...
175 foreach my $name (keys %exports) {
176
177 # if we find one ...
178 if (defined &{$class . '::' . $name}) {
179 my $keyword = \&{$class . '::' . $name};
180
181 # make sure it is from Moose
182 my $pkg_name = eval { svref_2object($keyword)->GV->STASH->NAME };
183 next if $@;
184 next if $pkg_name ne 'Moose';
185
186 # and if it is from Moose then undef the slot
187 delete ${$class . '::'}{$name};
188 }
189 }
190 }
fcd84ca9 191}
192
e9bb8a31 193## Utility functions
194
78cd1d3b 195sub _load_all_classes {
e9bb8a31 196 foreach my $super (@_) {
197 # see if this is already
198 # loaded in the symbol table
199 next if _is_class_already_loaded($super);
200 # otherwise require it ...
201 ($super->require)
01a8e221 202 || confess "Could not load module '$super' because : " . $UNIVERSAL::require::ERROR;
e9bb8a31 203 }
204}
205
d7f17ebb 206sub _is_class_already_loaded {
207 my $name = shift;
208 no strict 'refs';
209 return 1 if defined ${"${name}::VERSION"} || defined @{"${name}::ISA"};
210 foreach (keys %{"${name}::"}) {
211 next if substr($_, -2, 2) eq '::';
212 return 1 if defined &{"${name}::$_"};
213 }
214 return 0;
215}
216
fcd84ca9 2171;
218
219__END__
220
221=pod
222
223=head1 NAME
224
31f8ec72 225Moose - A complete modern object system for Perl 5
fcd84ca9 226
227=head1 SYNOPSIS
e522431d 228
229 package Point;
43d599e5 230 use strict;
231 use warnings;
e522431d 232 use Moose;
233
43d599e5 234 has 'x' => (is => 'rw', isa => 'Int');
235 has 'y' => (is => 'rw', isa => 'Int');
e522431d 236
237 sub clear {
238 my $self = shift;
239 $self->x(0);
240 $self->y(0);
241 }
242
243 package Point3D;
43d599e5 244 use strict;
245 use warnings;
e522431d 246 use Moose;
247
248 extends 'Point';
09fdc1dc 249
43d599e5 250 has 'z' => (is => 'rw', isa => 'Int');
e522431d 251
252 after 'clear' => sub {
253 my $self = shift;
43d599e5 254 $self->z(0);
e522431d 255 };
256
257=head1 CAVEAT
258
2c0cbef7 259Moose is a rapidly maturing module, and is already being used by
260a number of people. It's test suite is growing larger by the day,
261and the docs should soon follow.
262
263This said, Moose is not yet finished, and should still be considered
264to be evolving. Much of the outer API is stable, but the internals
265are still subject to change (although not without serious thought
266given to it).
267
268For more details, please refer to the L<FUTURE PLANS> section of
269this document.
e522431d 270
fcd84ca9 271=head1 DESCRIPTION
272
e522431d 273Moose is an extension of the Perl 5 object system.
274
275=head2 Another object system!?!?
fcd84ca9 276
e522431d 277Yes, I know there has been an explosion recently of new ways to
278build object's in Perl 5, most of them based on inside-out objects,
279and other such things. Moose is different because it is not a new
280object system for Perl 5, but instead an extension of the existing
281object system.
3c7278fb 282
e522431d 283Moose is built on top of L<Class::MOP>, which is a metaclass system
284for Perl 5. This means that Moose not only makes building normal
505c6fac 285Perl 5 objects better, but it also provides the power of metaclass
286programming.
e522431d 287
2c0cbef7 288=head2 Can I use this in production? Or is this just an experiment?
e522431d 289
2c0cbef7 290Moose is I<based> on the prototypes and experiments I did for the Perl 6
291meta-model, however Moose is B<NOT> an experiment/prototype, it is
43d599e5 292for B<real>. I will be deploying Moose into production environments later
293this year, and I have all intentions of using it as my de-facto class
294builderfrom now on.
e522431d 295
43d599e5 296=head2 Is Moose just Perl 6 in Perl 5?
e522431d 297
2c0cbef7 298No. While Moose is very much inspired by Perl 6, it is not. Instead, it
43d599e5 299is an OO system for Perl 5. I built Moose because I was tired or writing
300the same old boring Perl 5 OO code, and drooling over Perl 6 OO. So
301instead of switching to Ruby, I wrote Moose :)
3c7278fb 302
6ba6d68c 303=head1 BUILDING CLASSES WITH MOOSE
304
305Moose makes every attempt to provide as much convience during class
306construction/definition, but still stay out of your way if you want
43d599e5 307it to. Here are a few items to note when building classes with Moose.
6ba6d68c 308
309Unless specified with C<extends>, any class which uses Moose will
310inherit from L<Moose::Object>.
311
312Moose will also manage all attributes (including inherited ones) that
313are defined with C<has>. And assuming that you call C<new> which is
314inherited from L<Moose::Object>, then this includes properly initializing
315all instance slots, setting defaults where approprtiate and performing any
316type constraint checking or coercion.
317
318=head1 EXPORTED FUNCTIONS
319
320Moose will export a number of functions into the class's namespace, which
321can then be used to set up the class. These functions all work directly
322on the current class.
323
324=over 4
325
326=item B<meta>
327
328This is a method which provides access to the current class's metaclass.
329
330=item B<extends (@superclasses)>
331
332This function will set the superclass(es) for the current class.
333
334This approach is recommended instead of C<use base>, because C<use base>
335actually C<push>es onto the class's C<@ISA>, whereas C<extends> will
336replace it. This is important to ensure that classes which do not have
337superclasses properly inherit from L<Moose::Object>.
338
43d599e5 339=item B<with (@roles)>
e9ec68d6 340
43d599e5 341This will apply a given set of C<@roles> to the local class. Role support
2c0cbef7 342is currently under heavy development, see L<Moose::Role> for more details.
e9ec68d6 343
6ba6d68c 344=item B<has ($name, %options)>
345
346This will install an attribute of a given C<$name> into the current class.
43d599e5 347The list of C<%options> are the same as those provided by
348L<Class::MOP::Attribute>, in addition to the list below which are provided
349by Moose (L<Moose::Meta::Attribute> to be more specific):
6ba6d68c 350
351=over 4
352
076c81ed 353=item I<is =E<gt> 'rw'|'ro'>
6ba6d68c 354
355The I<is> option accepts either I<rw> (for read/write) or I<ro> (for read
356only). These will create either a read/write accessor or a read-only
357accessor respectively, using the same name as the C<$name> of the attribute.
358
359If you need more control over how your accessors are named, you can use the
43d599e5 360I<reader>, I<writer> and I<accessor> options inherited from L<Class::MOP::Attribute>.
6ba6d68c 361
076c81ed 362=item I<isa =E<gt> $type_name>
6ba6d68c 363
364The I<isa> option uses Moose's type constraint facilities to set up runtime
365type checking for this attribute. Moose will perform the checks during class
366construction, and within any accessors. The C<$type_name> argument must be a
367string. The string can be either a class name, or a type defined using
368Moose's type defintion features.
369
daea75c9 370=item I<coerce =E<gt> (1|0)>
371
372This will attempt to use coercion with the supplied type constraint to change
373the value passed into any accessors of constructors. You B<must> have supplied
374a type constraint in order for this to work. See L<Moose::Cookbook::Recipe5>
375for an example usage.
376
377=item I<does =E<gt> $role_name>
378
379This will accept the name of a role which the value stored in this attribute
380is expected to have consumed.
381
382=item I<required =E<gt> (1|0)>
383
384This marks the attribute as being required. This means a value must be supplied
385during class construction, and the attribute can never be set to C<undef> with
386an accessor.
387
388=item I<weak_ref =E<gt> (1|0)>
389
390This will tell the class to strore the value of this attribute as a weakened
391reference. If an attribute is a weakened reference, it can B<not> also be coerced.
392
393=item I<lazy =E<gt> (1|0)>
394
395This will tell the class to not create this slot until absolutely nessecary.
396If an attribute is marked as lazy it B<must> have a default supplied.
397
9e93dd19 398=item I<auto_deref =E<gt> (1|0)>
399
400This tells the accessor whether to automatically de-reference the value returned.
401This is only legal if your C<isa> option is either an C<ArrayRef> or C<HashRef>.
402
daea75c9 403=item I<trigger =E<gt> $code>
404
405The trigger option is a CODE reference which will be called after the value of
406the attribute is set. The CODE ref will be passed the instance itself, the
407updated value and the attribute meta-object (this is for more advanced fiddling
cce8198b 408and can typically be ignored in most cases). You can B<not> have a trigger on
409a read-only attribute.
daea75c9 410
2c0cbef7 411=item I<handles =E<gt> [ @handles ]>
412
413There is experimental support for attribute delegation using the C<handles>
414option. More docs to come later.
415
6ba6d68c 416=back
417
076c81ed 418=item B<before $name|@names =E<gt> sub { ... }>
6ba6d68c 419
076c81ed 420=item B<after $name|@names =E<gt> sub { ... }>
6ba6d68c 421
076c81ed 422=item B<around $name|@names =E<gt> sub { ... }>
6ba6d68c 423
424This three items are syntactic sugar for the before, after and around method
425modifier features that L<Class::MOP> provides. More information on these can
426be found in the L<Class::MOP> documentation for now.
427
159da176 428=item B<super>
429
430The keyword C<super> is a noop when called outside of an C<override> method. In
431the context of an C<override> method, it will call the next most appropriate
432superclass method with the same arguments as the original method.
433
434=item B<override ($name, &sub)>
435
436An C<override> method, is a way of explictly saying "I am overriding this
437method from my superclass". You can call C<super> within this method, and
438it will work as expected. The same thing I<can> be accomplished with a normal
439method call and the C<SUPER::> pseudo-package, it is really your choice.
440
441=item B<inner>
442
443The keyword C<inner>, much like C<super>, is a no-op outside of the context of
444an C<augment> method. You can think of C<inner> as being the inverse of
445C<super>, the details of how C<inner> and C<augment> work is best described in
446the L<Moose::Cookbook>.
447
448=item B<augment ($name, &sub)>
449
450An C<augment> method, is a way of explictly saying "I am augmenting this
451method from my superclass". Once again, the details of how C<inner> and
452C<augment> work is best described in the L<Moose::Cookbook>.
453
6ba6d68c 454=item B<confess>
455
456This is the C<Carp::confess> function, and exported here beause I use it
457all the time. This feature may change in the future, so you have been warned.
458
459=item B<blessed>
460
461This is the C<Scalar::Uti::blessed> function, it is exported here beause I
462use it all the time. It is highly recommended that this is used instead of
463C<ref> anywhere you need to test for an object's class name.
464
465=back
466
31f8ec72 467=head1 UNEXPORTING FUNCTIONS
468
469=head2 B<unimport>
470
471Moose offers a way of removing the keywords it exports though the C<unimport>
472method. You simply have to say C<no Moose> at the bottom of your code for this
473to work. Here is an example:
474
475 package Person;
476 use Moose;
477
478 has 'first_name' => (is => 'rw', isa => 'Str');
479 has 'last_name' => (is => 'rw', isa => 'Str');
480
481 sub full_name {
482 my $self = shift;
483 $self->first_name . ' ' . $self->last_name
484 }
485
486 no Moose; # keywords are removed from the Person package
487
f008ac1f 488=head1 ROAD MAP
2c0cbef7 489
f008ac1f 490We have developed a roadmap for the next several releases of Moose.
491Development is currently moving at a rapid pace, so this roughly
492represents the next few weeks of Moose.
2c0cbef7 493
494=over 4
495
f008ac1f 496=item 0.12
497
498This is the current release, it addresses some inconsistencies with
499Role composition and method modifiers. As an intermediate step, it
500removed method modifiers from Roles entirely, and roles can only
501compose methods and attributes.
502
503=item 0.13
504
505With this release will be adding a new keyword which will allow a
506finer grained form of reuse than roles. This keyword will form the
507basis of the features of the next few releases.
508
509=item 0.14
510
511With this release we will introduce a deferred version of method
512modifiers and a package/class-like container to hold them. In
513conjunction with the new keyword from 0.13, this will bring back
514the ability to compose groups of method modifiers which was
515removed in 0.12.
516
517=item 0.15
518
519With this release we will attempt to return the ability for Roles
520to compose method modifiers, by using the features introduced in
5210.13 and 0.14.
2c0cbef7 522
f008ac1f 523It is our intention that this release will bring Roles to a
524fully stable level.
2c0cbef7 525
f008ac1f 526=item 0.16 - 0.20
2c0cbef7 527
f008ac1f 528The focus of these releases will be to bring the optimization
529capabilities of class immutability which we introduced in
530Class::MOP 0.30. I will get into the details of this as we
531get closer to it.
2c0cbef7 532
533=back
534
535=head1 MISC.
536
537=head2 What does Moose stand for??
538
539Moose doesn't stand for one thing in particular, however, if you
540want, here are a few of my favorites, feel free to contribute
541more :)
542
543=over 4
544
545=item Make Other Object Systems Envious
546
547=item Makes Object Orientation So Easy
548
549=item Makes Object Orientation Spiffy- Er (sorry ingy)
550
551=item Most Other Object Systems Emasculate
552
2c0cbef7 553=item Moose Often Ovulate Sorta Early
554
2c0cbef7 555=item Moose Offers Often Super Extensions
556
557=item Meta Object Orientation Syntax Extensions
558
559=back
560
05d9eaf6 561=head1 CAVEATS
562
563=over 4
564
565=item *
566
567It should be noted that C<super> and C<inner> can B<not> be used in the same
568method. However, they can be combined together with the same class hierarchy,
569see F<t/014_override_augment_inner_super.t> for an example.
570
571The reason that this is so is because C<super> is only valid within a method
572with the C<override> modifier, and C<inner> will never be valid within an
573C<override> method. In fact, C<augment> will skip over any C<override> methods
574when searching for it's appropriate C<inner>.
575
576This might seem like a restriction, but I am of the opinion that keeping these
577two features seperate (but interoperable) actually makes them easy to use since
578their behavior is then easier to predict. Time will tell if I am right or not.
579
580=back
581
5569c072 582=head1 ACKNOWLEDGEMENTS
583
584=over 4
585
54c189df 586=item I blame Sam Vilain for introducing me to the insanity that is meta-models.
5569c072 587
54c189df 588=item I blame Audrey Tang for then encouraging my meta-model habit in #perl6.
5569c072 589
076c81ed 590=item Without Yuval "nothingmuch" Kogman this module would not be possible,
54c189df 591and it certainly wouldn't have this name ;P
5569c072 592
593=item The basis of the TypeContraints module was Rob Kinyon's idea
594originally, I just ran with it.
595
076c81ed 596=item Thanks to mst & chansen and the whole #moose poose for all the
d46a48f3 597ideas/feature-requests/encouragement
598
5569c072 599=back
600
e90c03d0 601=head1 SEE ALSO
602
603=over 4
604
6ba6d68c 605=item L<Class::MOP> documentation
606
607=item The #moose channel on irc.perl.org
608
e90c03d0 609=item L<http://forum2.org/moose/>
610
159da176 611=item L<http://www.cs.utah.edu/plt/publications/oopsla04-gff.pdf>
612
613This paper (suggested by lbr on #moose) was what lead to the implementation
614of the C<super>/C<overrride> and C<inner>/C<augment> features. If you really
615want to understand this feature, I suggest you read this.
616
e90c03d0 617=back
618
fcd84ca9 619=head1 BUGS
620
621All complex software has bugs lurking in it, and this module is no
622exception. If you find a bug please either email me, or add the bug
623to cpan-RT.
624
fcd84ca9 625=head1 AUTHOR
626
627Stevan Little E<lt>stevan@iinteractive.comE<gt>
628
db1ab48d 629Christian Hansen E<lt>chansen@cpan.orgE<gt>
630
631Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt>
98aae381 632
fcd84ca9 633=head1 COPYRIGHT AND LICENSE
634
635Copyright 2006 by Infinity Interactive, Inc.
636
637L<http://www.iinteractive.com>
638
639This library is free software; you can redistribute it and/or modify
640it under the same terms as Perl itself.
641
ddd0ec20 642=cut