Add some support for coercing to ArrayRef or HashRef for collection purposes
[gitmo/Moose.git] / lib / Moose.pm
CommitLineData
fcd84ca9 1
2package Moose;
3
4use strict;
5use warnings;
6
8de73ff1 7our $VERSION = '0.32';
d44714be 8our $AUTHORITY = 'cpan:STEVAN';
fcd84ca9 9
cc65ead0 10use Scalar::Util 'blessed', 'reftype';
3796382a 11use Carp 'confess';
12use Sub::Name 'subname';
13use B 'svref_2object';
fcd84ca9 14
2d562421 15use Sub::Exporter;
7f18097c 16
1edfdf1c 17use Class::MOP 0.46;
ef1d5f4b 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
d67145ed 25use Moose::Meta::Role;
26
fcd84ca9 27use Moose::Object;
7415b2cb 28use Moose::Util::TypeConstraints;
a15dff8d 29
a3c7e2fe 30{
be33e4f3 31 my $CALLER;
9bcfbab1 32
33 sub init_meta {
34 my ( $class, $base_class, $metaclass ) = @_;
72bbc189 35 $base_class = $class unless defined $base_class;
26fbace8 36 $metaclass = 'Moose::Meta::Class' unless defined $metaclass;
9bcfbab1 37
38 confess
39 "The Metaclass $metaclass must be a subclass of Moose::Meta::Class."
40 unless $metaclass->isa('Moose::Meta::Class');
a3c7e2fe 41
a3c7e2fe 42 # make a subtype for each Moose class
9bcfbab1 43 subtype $class => as 'Object' => where { $_->isa($class) } =>
44 optimize_as { blessed( $_[0] ) && $_[0]->isa($class) }
a3c7e2fe 45 unless find_type_constraint($class);
46
47 my $meta;
9bcfbab1 48 if ( $class->can('meta') ) {
fcec2383 49 # NOTE:
9bcfbab1 50 # this is the case where the metaclass pragma
51 # was used before the 'use Moose' statement to
fcec2383 52 # override a specific class
a3c7e2fe 53 $meta = $class->meta();
9bcfbab1 54 ( blessed($meta) && $meta->isa('Moose::Meta::Class') )
1edfdf1c 55 || confess "You already have a &meta function, but it does not return a Moose::Meta::Class";
a3c7e2fe 56 }
57 else {
fcec2383 58 # NOTE:
9bcfbab1 59 # this is broken currently, we actually need
60 # to allow the possiblity of an inherited
61 # meta, which will not be visible until the
62 # user 'extends' first. This needs to have
63 # more intelligence to it
64 $meta = $metaclass->initialize($class);
65 $meta->add_method(
66 'meta' => sub {
67
68 # re-initialize so it inherits properly
69 $metaclass->initialize( blessed( $_[0] ) || $_[0] );
70 }
71 );
a3c7e2fe 72 }
73
74 # make sure they inherit from Moose::Object
72bbc189 75 $meta->superclasses($base_class)
9bcfbab1 76 unless $meta->superclasses();
a3c7e2fe 77 }
78
79 my %exports = (
80 extends => sub {
be33e4f3 81 my $class = $CALLER;
68117c45 82 return subname 'Moose::extends' => sub (@) {
83 confess "Must derive at least one class" unless @_;
1eaed09d 84 Class::MOP::load_class($_) for @_;
9bcfbab1 85
86 # this checks the metaclass to make sure
87 # it is correct, sometimes it can get out
1341f10c 88 # of sync when the classes are being built
89 my $meta = $class->meta->_fix_metaclass_incompatability(@_);
be33e4f3 90 $meta->superclasses(@_);
a3c7e2fe 91 };
92 },
93 with => sub {
be33e4f3 94 my $class = $CALLER;
68117c45 95 return subname 'Moose::with' => sub (@) {
db1ab48d 96 my (@roles) = @_;
68117c45 97 confess "Must specify at least one role" unless @roles;
1eaed09d 98 Class::MOP::load_class($_) for @roles;
1341f10c 99 $class->meta->_apply_all_roles(@roles);
a3c7e2fe 100 };
101 },
102 has => sub {
be33e4f3 103 my $class = $CALLER;
2c0cbef7 104 return subname 'Moose::has' => sub ($;%) {
9bcfbab1 105 my ( $name, %options ) = @_;
106 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
107 $class->meta->_process_attribute( $_, %options ) for @$attrs;
a3c7e2fe 108 };
109 },
110 before => sub {
be33e4f3 111 my $class = $CALLER;
2c0cbef7 112 return subname 'Moose::before' => sub (@&) {
a3c7e2fe 113 my $code = pop @_;
be33e4f3 114 my $meta = $class->meta;
9bcfbab1 115 $meta->add_before_method_modifier( $_, $code ) for @_;
a3c7e2fe 116 };
117 },
118 after => sub {
be33e4f3 119 my $class = $CALLER;
2c0cbef7 120 return subname 'Moose::after' => sub (@&) {
a3c7e2fe 121 my $code = pop @_;
be33e4f3 122 my $meta = $class->meta;
9bcfbab1 123 $meta->add_after_method_modifier( $_, $code ) for @_;
a3c7e2fe 124 };
125 },
126 around => sub {
9bcfbab1 127 my $class = $CALLER;
2c0cbef7 128 return subname 'Moose::around' => sub (@&) {
a3c7e2fe 129 my $code = pop @_;
be33e4f3 130 my $meta = $class->meta;
9bcfbab1 131 $meta->add_around_method_modifier( $_, $code ) for @_;
a3c7e2fe 132 };
133 },
134 super => sub {
52c7c330 135 {
9bcfbab1 136 our %SUPER_SLOT;
137 no strict 'refs';
138 $SUPER_SLOT{$CALLER} = \*{"${CALLER}::super"};
52c7c330 139 }
9bcfbab1 140 return subname 'Moose::super' => sub { };
a3c7e2fe 141 },
142 override => sub {
be33e4f3 143 my $class = $CALLER;
2c0cbef7 144 return subname 'Moose::override' => sub ($&) {
9bcfbab1 145 my ( $name, $method ) = @_;
146 $class->meta->add_override_method_modifier( $name => $method );
a3c7e2fe 147 };
148 },
149 inner => sub {
52c7c330 150 {
9bcfbab1 151 our %INNER_SLOT;
152 no strict 'refs';
153 $INNER_SLOT{$CALLER} = \*{"${CALLER}::inner"};
52c7c330 154 }
9bcfbab1 155 return subname 'Moose::inner' => sub { };
a3c7e2fe 156 },
157 augment => sub {
be33e4f3 158 my $class = $CALLER;
2c0cbef7 159 return subname 'Moose::augment' => sub (@&) {
9bcfbab1 160 my ( $name, $method ) = @_;
161 $class->meta->add_augment_method_modifier( $name => $method );
a3c7e2fe 162 };
163 },
164 confess => sub {
165 return \&Carp::confess;
166 },
167 blessed => sub {
168 return \&Scalar::Util::blessed;
66bcefc1 169 },
a3c7e2fe 170 );
3d544ed5 171
9bcfbab1 172 my $exporter = Sub::Exporter::build_exporter(
173 {
174 exports => \%exports,
175 groups => { default => [':all'] }
a3c7e2fe 176 }
9bcfbab1 177 );
178
c92c1205 179 # 1 extra level because it's called by import so there's a layer of indirection
180 sub _get_caller{
181 my $offset = 1;
26fbace8 182 return
c92c1205 183 ref $_[1] && defined $_[1]->{into}
184 ? $_[1]->{into}
185 : ref $_[1] && defined $_[1]->{into_level}
186 ? caller($offset + $_[1]->{into_level})
187 : caller($offset);
188 }
5bee491d 189
190 sub import {
c92c1205 191 $CALLER = _get_caller(@_);
26fbace8 192
c235cd98 193 strict->import;
9bcfbab1 194 warnings->import;
a3c7e2fe 195
196 # we should never export to main
197 return if $CALLER eq 'main';
9bcfbab1 198
199 init_meta( $CALLER, 'Moose::Object' );
200
a3c7e2fe 201 goto $exporter;
fcb7afc2 202 }
9bcfbab1 203
31f8ec72 204 sub unimport {
9bcfbab1 205 no strict 'refs';
c92c1205 206 my $class = _get_caller(@_);
9bcfbab1 207
31f8ec72 208 # loop through the exports ...
9bcfbab1 209 foreach my $name ( keys %exports ) {
210
31f8ec72 211 # if we find one ...
9bcfbab1 212 if ( defined &{ $class . '::' . $name } ) {
213 my $keyword = \&{ $class . '::' . $name };
214
31f8ec72 215 # make sure it is from Moose
9bcfbab1 216 my $pkg_name =
217 eval { svref_2object($keyword)->GV->STASH->NAME };
31f8ec72 218 next if $@;
219 next if $pkg_name ne 'Moose';
9bcfbab1 220
31f8ec72 221 # and if it is from Moose then undef the slot
9bcfbab1 222 delete ${ $class . '::' }{$name};
31f8ec72 223 }
224 }
225 }
9bcfbab1 226
fcd84ca9 227}
228
8ecb1fa0 229## make 'em all immutable
230
231$_->meta->make_immutable(
232 inline_constructor => 0,
77a18c28 233 inline_accessors => 1, # these are Class::MOP accessors, so they need inlining
9bcfbab1 234 )
235 for (
8ecb1fa0 236 'Moose::Meta::Attribute',
237 'Moose::Meta::Class',
238 'Moose::Meta::Instance',
239
240 'Moose::Meta::TypeConstraint',
241 'Moose::Meta::TypeConstraint::Union',
0fbd4b0a 242 'Moose::Meta::TypeConstraint::Parameterized',
8ecb1fa0 243 'Moose::Meta::TypeCoercion',
244
245 'Moose::Meta::Method',
246 'Moose::Meta::Method::Accessor',
247 'Moose::Meta::Method::Constructor',
9bcfbab1 248 'Moose::Meta::Method::Destructor',
8ecb1fa0 249 'Moose::Meta::Method::Overriden',
d67145ed 250
251 'Moose::Meta::Role',
9bcfbab1 252 'Moose::Meta::Role::Method',
253 'Moose::Meta::Role::Method::Required',
254 );
8ecb1fa0 255
fcd84ca9 2561;
257
258__END__
259
260=pod
261
262=head1 NAME
263
31f8ec72 264Moose - A complete modern object system for Perl 5
fcd84ca9 265
266=head1 SYNOPSIS
e522431d 267
268 package Point;
1cd45431 269 use Moose; # automatically turns on strict and warnings
26fbace8 270
43d599e5 271 has 'x' => (is => 'rw', isa => 'Int');
272 has 'y' => (is => 'rw', isa => 'Int');
26fbace8 273
e522431d 274 sub clear {
275 my $self = shift;
276 $self->x(0);
26fbace8 277 $self->y(0);
e522431d 278 }
26fbace8 279
e522431d 280 package Point3D;
281 use Moose;
26fbace8 282
e522431d 283 extends 'Point';
26fbace8 284
43d599e5 285 has 'z' => (is => 'rw', isa => 'Int');
26fbace8 286
e522431d 287 after 'clear' => sub {
288 my $self = shift;
43d599e5 289 $self->z(0);
26fbace8 290 };
2c0cbef7 291
fcd84ca9 292=head1 DESCRIPTION
293
26fbace8 294Moose is an extension of the Perl 5 object system.
e522431d 295
296=head2 Another object system!?!?
fcd84ca9 297
26fbace8 298Yes, I know there has been an explosion recently of new ways to
68efb014 299build object's in Perl 5, most of them based on inside-out objects
26fbace8 300and other such things. Moose is different because it is not a new
301object system for Perl 5, but instead an extension of the existing
e522431d 302object system.
3c7278fb 303
26fbace8 304Moose is built on top of L<Class::MOP>, which is a metaclass system
305for Perl 5. This means that Moose not only makes building normal
306Perl 5 objects better, but it also provides the power of metaclass
505c6fac 307programming.
e522431d 308
734d1752 309=head2 Is this for real? Or is this just an experiment?
e522431d 310
2c0cbef7 311Moose is I<based> on the prototypes and experiments I did for the Perl 6
26fbace8 312meta-model. However, Moose is B<NOT> an experiment/prototype; it is for B<real>.
734d1752 313
26fbace8 314=head2 Is this ready for use in production?
d44714be 315
26fbace8 316Yes, I believe that it is.
734d1752 317
26fbace8 318Moose has been used successfully in production environemnts by several people
319and companies (including the one I work for). There are Moose applications
320which have been in production with little or no issue now for over a year.
321I consider it highly stable and we are commited to keeping it stable.
e522431d 322
26fbace8 323Of course, in the end, you need to make this call yourself. If you have
324any questions or concerns, please feel free to email me, or even the list
d44714be 325or just stop by #moose and ask away.
326
43d599e5 327=head2 Is Moose just Perl 6 in Perl 5?
e522431d 328
68efb014 329No. While Moose is very much inspired by Perl 6, it is not itself Perl 6.
1cd45431 330Instead, it is an OO system for Perl 5. I built Moose because I was tired of
68efb014 331writing the same old boring Perl 5 OO code, and drooling over Perl 6 OO. So
332instead of switching to Ruby, I wrote Moose :)
3c7278fb 333
28669f89 334=head2 Moose Extensions
335
336The L<MooseX::> namespace is the official place to find Moose extensions.
0b26305c 337There are a number of these modules out on CPAN right now the best way to
338find them is to search for MooseX:: on search.cpan.org.
28669f89 339
6ba6d68c 340=head1 BUILDING CLASSES WITH MOOSE
341
68efb014 342Moose makes every attempt to provide as much convenience as possible during
343class construction/definition, but still stay out of your way if you want it
344to. Here are a few items to note when building classes with Moose.
6ba6d68c 345
26fbace8 346Unless specified with C<extends>, any class which uses Moose will
6ba6d68c 347inherit from L<Moose::Object>.
348
1cd45431 349Moose will also manage all attributes (including inherited ones) that are
350defined with C<has>. And (assuming you call C<new>, which is inherited from
351L<Moose::Object>) this includes properly initializing all instance slots,
352setting defaults where appropriate, and performing any type constraint checking
353or coercion.
6ba6d68c 354
355=head1 EXPORTED FUNCTIONS
356
26fbace8 357Moose will export a number of functions into the class's namespace which
358may then be used to set up the class. These functions all work directly
6ba6d68c 359on the current class.
360
361=over 4
362
363=item B<meta>
364
365This is a method which provides access to the current class's metaclass.
366
367=item B<extends (@superclasses)>
368
369This function will set the superclass(es) for the current class.
370
26fbace8 371This approach is recommended instead of C<use base>, because C<use base>
372actually C<push>es onto the class's C<@ISA>, whereas C<extends> will
373replace it. This is important to ensure that classes which do not have
68efb014 374superclasses still properly inherit from L<Moose::Object>.
6ba6d68c 375
43d599e5 376=item B<with (@roles)>
e9ec68d6 377
26fbace8 378This will apply a given set of C<@roles> to the local class. Role support
68efb014 379is currently under heavy development; see L<Moose::Role> for more details.
e9ec68d6 380
cd7eeaf5 381=item B<has $name =E<gt> %options>
6ba6d68c 382
26fbace8 383This will install an attribute of a given C<$name> into the current class.
384The C<%options> are the same as those provided by
385L<Class::MOP::Attribute>, in addition to the list below which are provided
43d599e5 386by Moose (L<Moose::Meta::Attribute> to be more specific):
6ba6d68c 387
388=over 4
389
076c81ed 390=item I<is =E<gt> 'rw'|'ro'>
6ba6d68c 391
26fbace8 392The I<is> option accepts either I<rw> (for read/write) or I<ro> (for read
393only). These will create either a read/write accessor or a read-only
6ba6d68c 394accessor respectively, using the same name as the C<$name> of the attribute.
395
1cd45431 396If you need more control over how your accessors are named, you can use the
397I<reader>, I<writer> and I<accessor> options inherited from
398L<Class::MOP::Attribute>.
6ba6d68c 399
076c81ed 400=item I<isa =E<gt> $type_name>
6ba6d68c 401
26fbace8 402The I<isa> option uses Moose's type constraint facilities to set up runtime
403type checking for this attribute. Moose will perform the checks during class
404construction, and within any accessors. The C<$type_name> argument must be a
405string. The string may be either a class name or a type defined using
9cca2e9e 406Moose's type definition features. (Refer to L<Moose::Util::TypeConstraints>
c2a69ef1 407for information on how to define a new type, and how to retrieve type meta-data).
6ba6d68c 408
daea75c9 409=item I<coerce =E<gt> (1|0)>
410
26fbace8 411This will attempt to use coercion with the supplied type constraint to change
412the value passed into any accessors or constructors. You B<must> have supplied
daea75c9 413a type constraint in order for this to work. See L<Moose::Cookbook::Recipe5>
1cd45431 414for an example.
daea75c9 415
416=item I<does =E<gt> $role_name>
417
26fbace8 418This will accept the name of a role which the value stored in this attribute
daea75c9 419is expected to have consumed.
420
421=item I<required =E<gt> (1|0)>
422
26fbace8 423This marks the attribute as being required. This means a I<defined> value must be
424supplied during class construction, and the attribute may never be set to
425C<undef> with an accessor.
daea75c9 426
427=item I<weak_ref =E<gt> (1|0)>
428
68efb014 429This will tell the class to store the value of this attribute as a weakened
430reference. If an attribute is a weakened reference, it B<cannot> also be
431coerced.
daea75c9 432
433=item I<lazy =E<gt> (1|0)>
434
26fbace8 435This will tell the class to not create this slot until absolutely necessary.
daea75c9 436If an attribute is marked as lazy it B<must> have a default supplied.
437
9e93dd19 438=item I<auto_deref =E<gt> (1|0)>
439
26fbace8 440This tells the accessor whether to automatically dereference the value returned.
1cd45431 441This is only legal if your C<isa> option is either C<ArrayRef> or C<HashRef>.
9e93dd19 442
c1935ade 443=item I<metaclass =E<gt> $metaclass_name>
444
1cd45431 445This tells the class to use a custom attribute metaclass for this particular
446attribute. Custom attribute metaclasses are useful for extending the
447capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
448but they are still a fairly advanced topic and too much to cover here. I will
449try and write a recipe on them soon.
450
451The default behavior here is to just load C<$metaclass_name>; however, we also
452have a way to alias to a shorter name. This will first look to see if
453B<Moose::Meta::Attribute::Custom::$metaclass_name> exists. If it does, Moose
454will then check to see if that has the method C<register_implemenetation>, which
455should return the actual name of the custom attribute metaclass. If there is no
456C<register_implemenetation> method, it will fall back to using
c1935ade 457B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
458
daea75c9 459=item I<trigger =E<gt> $code>
460
1cd45431 461The I<trigger> option is a CODE reference which will be called after the value of
462the attribute is set. The CODE ref will be passed the instance itself, the
daea75c9 463updated value and the attribute meta-object (this is for more advanced fiddling
1cd45431 464and can typically be ignored). You B<cannot> have a trigger on a read-only
465attribute.
daea75c9 466
c84f324f 467=item I<handles =E<gt> ARRAY | HASH | REGEXP | ROLE | CODE>
2c0cbef7 468
26fbace8 469The I<handles> option provides Moose classes with automated delegation features.
470This is a pretty complex and powerful option. It accepts many different option
471formats, each with its own benefits and drawbacks.
38e3283b 472
1cd45431 473B<NOTE:> This feature is no longer experimental, but it may still have subtle
474bugs lurking in the deeper corners. If you think you have found a bug, you
26fbace8 475probably have, so please report it to me right away.
38e3283b 476
1cd45431 477B<NOTE:> The class being delegated to does not need to be a Moose based class,
478which is why this feature is especially useful when wrapping non-Moose classes.
38e3283b 479
1cd45431 480All I<handles> option formats share the following traits:
38e3283b 481
1cd45431 482You cannot override a locally defined method with a delegated method; an
483exception will be thrown if you try. That is to say, if you define C<foo> in
484your class, you cannot override it with a delegated C<foo>. This is almost never
485something you would want to do, and if it is, you should do it by hand and not
486use Moose.
38e3283b 487
1cd45431 488You cannot override any of the methods found in Moose::Object, or the C<BUILD>
489and C<DEMOLISH> methods. These will not throw an exception, but will silently
490move on to the next method in the list. My reasoning for this is that you would
491almost never want to do this, since it usually breaks your class. As with
492overriding locally defined methods, if you do want to do this, you should do it
493manually, not with Moose.
38e3283b 494
f3c4e20e 495You do not I<need> to have a reader (or accessor) for the attribute in order
496to delegate to it. Moose will create a means of accessing the value for you,
497however this will be several times B<less> efficient then if you had given
498the attribute a reader (or accessor) to use.
499
38e3283b 500Below is the documentation for each option format:
501
502=over 4
503
504=item C<ARRAY>
505
26fbace8 506This is the most common usage for I<handles>. You basically pass a list of
507method names to be delegated, and Moose will install a delegation method
1cd45431 508for each one.
38e3283b 509
510=item C<HASH>
511
26fbace8 512This is the second most common usage for I<handles>. Instead of a list of
513method names, you pass a HASH ref where each key is the method name you
514want installed locally, and its value is the name of the original method
515in the class being delegated to.
fd595040 516
26fbace8 517This can be very useful for recursive classes like trees. Here is a
fd595040 518quick example (soon to be expanded into a Moose::Cookbook::Recipe):
38e3283b 519
1cd45431 520 package Tree;
38e3283b 521 use Moose;
26fbace8 522
38e3283b 523 has 'node' => (is => 'rw', isa => 'Any');
26fbace8 524
38e3283b 525 has 'children' => (
526 is => 'ro',
527 isa => 'ArrayRef',
528 default => sub { [] }
529 );
26fbace8 530
38e3283b 531 has 'parent' => (
532 is => 'rw',
533 isa => 'Tree',
534 is_weak_ref => 1,
535 handles => {
536 parent_node => 'node',
26fbace8 537 siblings => 'children',
38e3283b 538 }
539 );
540
1cd45431 541In this example, the Tree package gets C<parent_node> and C<siblings> methods,
542which delegate to the C<node> and C<children> methods (respectively) of the Tree
26fbace8 543instance stored in the C<parent> slot.
38e3283b 544
545=item C<REGEXP>
546
26fbace8 547The regexp option works very similar to the ARRAY option, except that it builds
548the list of methods for you. It starts by collecting all possible methods of the
549class being delegated to, then filters that list using the regexp supplied here.
38e3283b 550
26fbace8 551B<NOTE:> An I<isa> option is required when using the regexp option format. This
552is so that we can determine (at compile time) the method list from the class.
38e3283b 553Without an I<isa> this is just not possible.
554
c84f324f 555=item C<ROLE>
556
26fbace8 557With the role option, you specify the name of a role whose "interface" then
558becomes the list of methods to handle. The "interface" can be defined as; the
559methods of the role and any required methods of the role. It should be noted
560that this does B<not> include any method modifiers or generated attribute
c84f324f 561methods (which is consistent with role composition).
562
38e3283b 563=item C<CODE>
564
1cd45431 565This is the option to use when you really want to do something funky. You should
566only use it if you really know what you are doing, as it involves manual
567metaclass twiddling.
38e3283b 568
1cd45431 569This takes a code reference, which should expect two arguments. The first is the
570attribute meta-object this I<handles> is attached to. The second is the
571metaclass of the class being delegated to. It expects you to return a hash (not
26fbace8 572a HASH ref) of the methods you want mapped.
38e3283b 573
574=back
2c0cbef7 575
6ba6d68c 576=back
577
cd7eeaf5 578=item B<has +$name =E<gt> %options>
579
26fbace8 580This is variation on the normal attibute creator C<has> which allows you to
cd7eeaf5 581clone and extend an attribute from a superclass. Here is a quick example:
582
583 package Foo;
584 use Moose;
26fbace8 585
cd7eeaf5 586 has 'message' => (
26fbace8 587 is => 'rw',
cd7eeaf5 588 isa => 'Str',
589 default => 'Hello, I am a Foo'
590 );
26fbace8 591
cd7eeaf5 592 package My::Foo;
593 use Moose;
26fbace8 594
cd7eeaf5 595 extends 'Foo';
26fbace8 596
cd7eeaf5 597 has '+message' => (default => 'Hello I am My::Foo');
598
1cd45431 599What is happening here is that B<My::Foo> is cloning the C<message> attribute
600from its parent class B<Foo>, retaining the C<is =E<gt> 'rw'> and C<isa =E<gt>
601'Str'> characteristics, but changing the value in C<default>.
cd7eeaf5 602
83cc9094 603This feature is restricted somewhat, so as to try and force at least I<some>
cd7eeaf5 604sanity into it. You are only allowed to change the following attributes:
605
606=over 4
607
26fbace8 608=item I<default>
cd7eeaf5 609
610Change the default value of an attribute.
611
26fbace8 612=item I<coerce>
cd7eeaf5 613
614Change whether the attribute attempts to coerce a value passed to it.
615
26fbace8 616=item I<required>
cd7eeaf5 617
618Change if the attribute is required to have a value.
619
620=item I<documentation>
621
622Change the documentation string associated with the attribute.
623
83cc9094 624=item I<lazy>
625
626Change if the attribute lazily initializes the slot.
627
cd7eeaf5 628=item I<isa>
629
1cd45431 630You I<are> allowed to change the type, B<if and only if> the new type is a
631subtype of the old type.
cd7eeaf5 632
83cc9094 633=item I<handles>
634
26fbace8 635You are allowed to B<add> a new C<handles> definition, but you are B<not>
636allowed to I<change> one.
83cc9094 637
cd7eeaf5 638=back
639
076c81ed 640=item B<before $name|@names =E<gt> sub { ... }>
6ba6d68c 641
076c81ed 642=item B<after $name|@names =E<gt> sub { ... }>
6ba6d68c 643
076c81ed 644=item B<around $name|@names =E<gt> sub { ... }>
6ba6d68c 645
d8af92ae 646This three items are syntactic sugar for the before, after, and around method
647modifier features that L<Class::MOP> provides. More information on these may be
648found in the L<Class::MOP::Class documentation|Class::MOP::Class/"Method
649Modifiers"> for now.
6ba6d68c 650
159da176 651=item B<super>
652
26fbace8 653The keyword C<super> is a no-op when called outside of an C<override> method. In
654the context of an C<override> method, it will call the next most appropriate
159da176 655superclass method with the same arguments as the original method.
656
657=item B<override ($name, &sub)>
658
26fbace8 659An C<override> method is a way of explicitly saying "I am overriding this
660method from my superclass". You can call C<super> within this method, and
661it will work as expected. The same thing I<can> be accomplished with a normal
662method call and the C<SUPER::> pseudo-package; it is really your choice.
159da176 663
664=item B<inner>
665
26fbace8 666The keyword C<inner>, much like C<super>, is a no-op outside of the context of
667an C<augment> method. You can think of C<inner> as being the inverse of
68efb014 668C<super>; the details of how C<inner> and C<augment> work is best described in
159da176 669the L<Moose::Cookbook>.
670
671=item B<augment ($name, &sub)>
672
26fbace8 673An C<augment> method, is a way of explicitly saying "I am augmenting this
674method from my superclass". Once again, the details of how C<inner> and
159da176 675C<augment> work is best described in the L<Moose::Cookbook>.
676
6ba6d68c 677=item B<confess>
678
68efb014 679This is the C<Carp::confess> function, and exported here because I use it
26fbace8 680all the time. This feature may change in the future, so you have been warned.
6ba6d68c 681
682=item B<blessed>
683
1cd45431 684This is the C<Scalar::Util::blessed> function, it is exported here because I
26fbace8 685use it all the time. It is highly recommended that this is used instead of
6ba6d68c 686C<ref> anywhere you need to test for an object's class name.
687
688=back
689
1cd45431 690=head1 UNIMPORTING FUNCTIONS
31f8ec72 691
692=head2 B<unimport>
693
1cd45431 694Moose offers a way to remove the keywords it exports, through the C<unimport>
31f8ec72 695method. You simply have to say C<no Moose> at the bottom of your code for this
696to work. Here is an example:
697
698 package Person;
699 use Moose;
700
701 has 'first_name' => (is => 'rw', isa => 'Str');
702 has 'last_name' => (is => 'rw', isa => 'Str');
26fbace8 703
704 sub full_name {
31f8ec72 705 my $self = shift;
26fbace8 706 $self->first_name . ' ' . $self->last_name
31f8ec72 707 }
26fbace8 708
709 no Moose; # keywords are removed from the Person package
31f8ec72 710
9bcfbab1 711=head1 EXTENDING AND EMBEDDING MOOSE
712
26fbace8 713Moose also offers some options for extending or embedding it into your own
9bcfbab1 714framework. The basic premise is to have something that sets up your class'
26fbace8 715metaclass and export the moose declarators (C<has>, C<with>, C<extends>,...).
9bcfbab1 716Here is an example:
717
718 package MyFramework;
719 use Moose;
26fbace8 720
9bcfbab1 721 sub import {
722 my $CALLER = caller();
723
724 strict->import;
725 warnings->import;
726
727 # we should never export to main
728 return if $CALLER eq 'main';
729 Moose::init_meta( $CALLER, 'MyFramework::Base' );
730 Moose->import({into => $CALLER});
731
732 # Do my custom framework stuff
26fbace8 733
9bcfbab1 734 return 1;
735 }
26fbace8 736
9bcfbab1 737=head2 B<import>
738
77a18c28 739Moose's C<import> method supports the L<Sub::Exporter> form of C<{into =E<gt> $pkg}>
9bcfbab1 740and C<{into_level =E<gt> 1}>
741
742=head2 B<init_meta ($class, $baseclass, $metaclass)>
743
26fbace8 744Moose does some boot strapping: it creates a metaclass object for your class,
745and then injects a C<meta> accessor into your class to retrieve it. Then it
746sets your baseclass to Moose::Object or the value you pass in unless you already
747have one. This is all done via C<init_meta> which takes the name of your class
2bbba362 748and optionally a baseclass and a metaclass as arguments.
26fbace8 749
05d9eaf6 750=head1 CAVEATS
751
752=over 4
753
754=item *
755
1cd45431 756It should be noted that C<super> and C<inner> B<cannot> be used in the same
757method. However, they may be combined within the same class hierarchy; see
758F<t/014_override_augment_inner_super.t> for an example.
05d9eaf6 759
26fbace8 760The reason for this is that C<super> is only valid within a method
761with the C<override> modifier, and C<inner> will never be valid within an
762C<override> method. In fact, C<augment> will skip over any C<override> methods
68efb014 763when searching for its appropriate C<inner>.
05d9eaf6 764
1cd45431 765This might seem like a restriction, but I am of the opinion that keeping these
766two features separate (yet interoperable) actually makes them easy to use, since
767their behavior is then easier to predict. Time will tell whether I am right or
c84f324f 768not (UPDATE: so far so good).
05d9eaf6 769
770=back
771
5569c072 772=head1 ACKNOWLEDGEMENTS
773
774=over 4
775
54c189df 776=item I blame Sam Vilain for introducing me to the insanity that is meta-models.
5569c072 777
54c189df 778=item I blame Audrey Tang for then encouraging my meta-model habit in #perl6.
5569c072 779
26fbace8 780=item Without Yuval "nothingmuch" Kogman this module would not be possible,
54c189df 781and it certainly wouldn't have this name ;P
5569c072 782
26fbace8 783=item The basis of the TypeContraints module was Rob Kinyon's idea
5569c072 784originally, I just ran with it.
785
26fbace8 786=item Thanks to mst & chansen and the whole #moose poose for all the
c84f324f 787early ideas/feature-requests/encouragement/bug-finding.
d46a48f3 788
68efb014 789=item Thanks to David "Theory" Wheeler for meta-discussions and spelling fixes.
790
5569c072 791=back
792
e90c03d0 793=head1 SEE ALSO
794
795=over 4
796
c84f324f 797=item L<http://www.iinteractive.com/moose>
798
799This is the official web home of Moose, it contains links to our public SVN repo
26fbace8 800as well as links to a number of talks and articles on Moose and Moose related
801technologies.
c84f324f 802
6ba6d68c 803=item L<Class::MOP> documentation
804
805=item The #moose channel on irc.perl.org
806
e67a0fca 807=item The Moose mailing list - moose@perl.org
808
c84f324f 809=item Moose stats on ohloh.net - L<http://www.ohloh.net/projects/5788>
810
28669f89 811=item Several Moose extension modules in the L<MooseX::> namespace.
812
c84f324f 813=back
814
26fbace8 815=head2 Papers
c84f324f 816
817=over 4
e90c03d0 818
159da176 819=item L<http://www.cs.utah.edu/plt/publications/oopsla04-gff.pdf>
820
26fbace8 821This paper (suggested by lbr on #moose) was what lead to the implementation
822of the C<super>/C<override> and C<inner>/C<augment> features. If you really
1cd45431 823want to understand them, I suggest you read this.
159da176 824
e90c03d0 825=back
826
fcd84ca9 827=head1 BUGS
828
26fbace8 829All complex software has bugs lurking in it, and this module is no
fcd84ca9 830exception. If you find a bug please either email me, or add the bug
831to cpan-RT.
832
fcd84ca9 833=head1 AUTHOR
834
835Stevan Little E<lt>stevan@iinteractive.comE<gt>
836
9af1d28b 837B<with contributions from:>
db1ab48d 838
9af1d28b 839Aankhen
840
841Adam (Alias) Kennedy
842
843Anders (Debolaz) Nor Berle
844
5868294f 845Nathan (kolibre) Gray
846
9af1d28b 847Christian (chansen) Hansen
848
e7f8d0c2 849Hans Dieter (confound) Pearcey
850
9af1d28b 851Eric (ewilhelm) Wilhelm
852
853Guillermo (groditi) Roditi
854
855Jess (castaway) Robinson
856
857Matt (mst) Trout
858
859Robert (phaylon) Sedlacek
860
861Robert (rlb3) Boone
862
863Scott (konobi) McWhirter
864
f44ae52f 865Shlomi (rindolf) Fish
866
9af1d28b 867Yuval (nothingmuch) Kogman
868
cbe25729 869Chris (perigrin) Prather
870
e46f5cc2 871Jonathan (jrockway) Rockway
872
3ccdc84a 873Piotr (dexter) Roszatycki
874
26fbace8 875Sam (mugwump) Vilain
f1917f58 876
9af1d28b 877... and many other #moose folks
98aae381 878
fcd84ca9 879=head1 COPYRIGHT AND LICENSE
880
b77fdbed 881Copyright 2006, 2007 by Infinity Interactive, Inc.
fcd84ca9 882
883L<http://www.iinteractive.com>
884
885This library is free software; you can redistribute it and/or modify
26fbace8 886it under the same terms as Perl itself.
fcd84ca9 887
ddd0ec20 888=cut