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