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