Bump version to 1.10
[gitmo/Moose.git] / lib / Moose.pm
CommitLineData
fcd84ca9 1package Moose;
d1e17c7f 2use strict;
3use warnings;
fcd84ca9 4
ecb1297a 5use 5.008;
6
db236a63 7our $VERSION = '1.10';
75b95414 8$VERSION = eval $VERSION;
d44714be 9our $AUTHORITY = 'cpan:STEVAN';
fcd84ca9 10
21f1e231 11use Scalar::Util 'blessed';
e2095e4a 12use Carp 'confess';
fcd84ca9 13
1fa1a58d 14use Moose::Deprecated;
5bd4db9b 15use Moose::Exporter;
7f18097c 16
88f6146f 17use Class::MOP 1.05;
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
0779da92 25use Moose::Object;
26
d67145ed 27use Moose::Meta::Role;
0779da92 28use Moose::Meta::Role::Composite;
29use Moose::Meta::Role::Application;
30use Moose::Meta::Role::Application::RoleSummation;
31use Moose::Meta::Role::Application::ToClass;
32use Moose::Meta::Role::Application::ToRole;
33use Moose::Meta::Role::Application::ToInstance;
d67145ed 34
7415b2cb 35use Moose::Util::TypeConstraints;
d7d8a8c7 36use Moose::Util ();
a15dff8d 37
17e5e226 38use Moose::Meta::Attribute::Native;
fafc8b9b 39
c245d69b 40sub throw_error {
d03bd989 41 # FIXME This
c245d69b 42 shift;
43 goto \&confess
44}
4c0b3599 45
5bd4db9b 46sub extends {
d5447d26 47 my $meta = shift;
3d544ed5 48
e2095e4a 49 Moose->throw_error("Must derive at least one class") unless @_;
9bcfbab1 50
5bd4db9b 51 # this checks the metaclass to make sure
52 # it is correct, sometimes it can get out
53 # of sync when the classes are being built
d5447d26 54 $meta->superclasses(@_);
5bd4db9b 55}
a3c7e2fe 56
5bd4db9b 57sub with {
d5447d26 58 Moose::Util::apply_all_roles(shift, @_);
5bd4db9b 59}
9bcfbab1 60
5bd4db9b 61sub has {
d5447d26 62 my $meta = shift;
63 my $name = shift;
e2095e4a 64
65 Moose->throw_error('Usage: has \'name\' => ( key => value, ... )')
db532c7d 66 if @_ % 2 == 1;
e2095e4a 67
833b56a7 68 my %options = ( definition_context => Moose::Util::_caller_info(), @_ );
5bd4db9b 69 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
d5447d26 70 $meta->add_attribute( $_, %options ) for @$attrs;
5bd4db9b 71}
9bcfbab1 72
5bd4db9b 73sub before {
d5447d26 74 Moose::Util::add_method_modifier(shift, 'before', \@_);
5bd4db9b 75}
76
77sub after {
d5447d26 78 Moose::Util::add_method_modifier(shift, 'after', \@_);
5bd4db9b 79}
80
81sub around {
d5447d26 82 Moose::Util::add_method_modifier(shift, 'around', \@_);
5bd4db9b 83}
84
991933fb 85our $SUPER_PACKAGE;
86our $SUPER_BODY;
87our @SUPER_ARGS;
88
5bd4db9b 89sub super {
991933fb 90 # This check avoids a recursion loop - see
91 # t/100_bugs/020_super_recursion.t
92 return if defined $SUPER_PACKAGE && $SUPER_PACKAGE ne caller();
93 return unless $SUPER_BODY; $SUPER_BODY->(@SUPER_ARGS);
5bd4db9b 94}
9bcfbab1 95
5bd4db9b 96sub override {
d5447d26 97 my $meta = shift;
5bd4db9b 98 my ( $name, $method ) = @_;
d5447d26 99 $meta->add_override_method_modifier( $name => $method );
5bd4db9b 100}
9bcfbab1 101
5bd4db9b 102sub inner {
103 my $pkg = caller();
104 our ( %INNER_BODY, %INNER_ARGS );
105
106 if ( my $body = $INNER_BODY{$pkg} ) {
107 my @args = @{ $INNER_ARGS{$pkg} };
108 local $INNER_ARGS{$pkg};
109 local $INNER_BODY{$pkg};
110 return $body->(@args);
111 } else {
112 return;
ce265cc3 113 }
5bd4db9b 114}
9bcfbab1 115
5bd4db9b 116sub augment {
d5447d26 117 my $meta = shift;
5bd4db9b 118 my ( $name, $method ) = @_;
d5447d26 119 $meta->add_augment_method_modifier( $name => $method );
ce265cc3 120}
9bcfbab1 121
aedcb7d9 122Moose::Exporter->setup_import_methods(
d5447d26 123 with_meta => [
348715c4 124 qw( extends with has before after around override augment )
97a93056 125 ],
126 as_is => [
127 qw( super inner ),
5bd4db9b 128 \&Carp::confess,
129 \&Scalar::Util::blessed,
130 ],
131);
132
cc841c0e 133sub init_meta {
085fba61 134 # This used to be called as a function. This hack preserves
135 # backwards compatibility.
136 if ( $_[0] ne __PACKAGE__ ) {
d69a348e 137 Moose::Deprecated::deprecated(
138 feature => 'Moose::init_meta',
139 message => 'Calling Moose::init_meta as a function is deprecated',
140 );
141
085fba61 142 return __PACKAGE__->init_meta(
143 for_class => $_[0],
144 base_class => $_[1],
145 metaclass => $_[2],
146 );
147 }
7c4676ef 148
0338a411 149 shift;
150 my %args = @_;
151
152 my $class = $args{for_class}
c245d69b 153 or Moose->throw_error("Cannot call init_meta without specifying a for_class");
085fba61 154 my $base_class = $args{base_class} || 'Moose::Object';
155 my $metaclass = $args{metaclass} || 'Moose::Meta::Class';
cc841c0e 156
c245d69b 157 Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Class.")
cc841c0e 158 unless $metaclass->isa('Moose::Meta::Class');
159
160 # make a subtype for each Moose class
161 class_type($class)
162 unless find_type_constraint($class);
163
164 my $meta;
50d5df60 165
166 if ( $meta = Class::MOP::get_metaclass_by_name($class) ) {
167 unless ( $meta->isa("Moose::Meta::Class") ) {
677eafe2 168 my $error_message = "$class already has a metaclass, but it does not inherit $metaclass ($meta).";
169 if ( $meta->isa('Moose::Meta::Role') ) {
170 Moose->throw_error($error_message . ' You cannot make the same thing a role and a class. Remove either Moose or Moose::Role.');
171 } else {
172 Moose->throw_error($error_message);
173 }
50d5df60 174 }
175 } else {
176 # no metaclass, no 'meta' method
177
178 # now we check whether our ancestors have metaclass, and if so borrow that
179 my ( undef, @isa ) = @{ $class->mro::get_linear_isa };
180
181 foreach my $ancestor ( @isa ) {
182 my $ancestor_meta = Class::MOP::get_metaclass_by_name($ancestor) || next;
183
184 my $ancestor_meta_class = ($ancestor_meta->is_immutable
989263ad 185 ? $ancestor_meta->_get_mutable_metaclass_name
50d5df60 186 : ref($ancestor_meta));
187
188 # if we have an ancestor metaclass that inherits $metaclass, we use
41419b9e 189 # that. This is like _fix_metaclass_incompatibility, but we can do it now.
50d5df60 190
191 # the case of having an ancestry is not very common, but arises in
192 # e.g. Reaction
193 unless ( $metaclass->isa( $ancestor_meta_class ) ) {
194 if ( $ancestor_meta_class->isa($metaclass) ) {
195 $metaclass = $ancestor_meta_class;
196 }
197 }
198 }
199
200 $meta = $metaclass->initialize($class);
201 }
202
cc841c0e 203 if ( $class->can('meta') ) {
50d5df60 204 # check 'meta' method
205
206 # it may be inherited
207
cc841c0e 208 # NOTE:
209 # this is the case where the metaclass pragma
210 # was used before the 'use Moose' statement to
211 # override a specific class
50d5df60 212 my $method_meta = $class->meta;
213
214 ( blessed($method_meta) && $method_meta->isa('Moose::Meta::Class') )
e7e9a4d8 215 || Moose->throw_error("$class already has a &meta function, but it does not return a Moose::Meta::Class ($method_meta)");
50d5df60 216
217 $meta = $method_meta;
cc841c0e 218 }
50d5df60 219
220 unless ( $meta->has_method("meta") ) { # don't overwrite
221 # also check for inherited non moose 'meta' method?
222 # FIXME also skip this if the user requested by passing an option
cc841c0e 223 $meta->add_method(
224 'meta' => sub {
225 # re-initialize so it inherits properly
50d5df60 226 $metaclass->initialize( ref($_[0]) || $_[0] );
cc841c0e 227 }
228 );
229 }
230
231 # make sure they inherit from Moose::Object
232 $meta->superclasses($base_class)
233 unless $meta->superclasses();
234
235 return $meta;
236}
237
085fba61 238# This may be used in some older MooseX extensions.
239sub _get_caller {
240 goto &Moose::Exporter::_get_caller;
241}
242
8ecb1fa0 243## make 'em all immutable
244
3cae4250 245$_->make_immutable(
0779da92 246 inline_constructor => 1,
247 constructor_name => "_new",
3cae4250 248 # these are Class::MOP accessors, so they need inlining
249 inline_accessors => 1
250 ) for grep { $_->is_mutable }
251 map { $_->meta }
252 qw(
0779da92 253 Moose::Meta::Attribute
254 Moose::Meta::Class
255 Moose::Meta::Instance
256
0779da92 257 Moose::Meta::TypeCoercion
258 Moose::Meta::TypeCoercion::Union
259
260 Moose::Meta::Method
261 Moose::Meta::Method::Accessor
262 Moose::Meta::Method::Constructor
263 Moose::Meta::Method::Destructor
74862722 264 Moose::Meta::Method::Overridden
0779da92 265 Moose::Meta::Method::Augmented
266
267 Moose::Meta::Role
f785aad8 268 Moose::Meta::Role::Attribute
0779da92 269 Moose::Meta::Role::Method
270 Moose::Meta::Role::Method::Required
bb153262 271 Moose::Meta::Role::Method::Conflicting
0779da92 272
273 Moose::Meta::Role::Composite
274
275 Moose::Meta::Role::Application
276 Moose::Meta::Role::Application::RoleSummation
277 Moose::Meta::Role::Application::ToClass
278 Moose::Meta::Role::Application::ToRole
279 Moose::Meta::Role::Application::ToInstance
3cae4250 280);
8ecb1fa0 281
f785aad8 282Moose::Meta::Mixin::AttributeCore->meta->make_immutable(
283 inline_constructor => 0,
284 constructor_name => undef,
285);
286
fcd84ca9 2871;
288
289__END__
290
291=pod
292
293=head1 NAME
294
8bdc7f13 295Moose - A postmodern object system for Perl 5
fcd84ca9 296
297=head1 SYNOPSIS
e522431d 298
299 package Point;
1cd45431 300 use Moose; # automatically turns on strict and warnings
26fbace8 301
43d599e5 302 has 'x' => (is => 'rw', isa => 'Int');
303 has 'y' => (is => 'rw', isa => 'Int');
26fbace8 304
e522431d 305 sub clear {
306 my $self = shift;
307 $self->x(0);
26fbace8 308 $self->y(0);
e522431d 309 }
26fbace8 310
e522431d 311 package Point3D;
312 use Moose;
26fbace8 313
e522431d 314 extends 'Point';
26fbace8 315
43d599e5 316 has 'z' => (is => 'rw', isa => 'Int');
26fbace8 317
e522431d 318 after 'clear' => sub {
319 my $self = shift;
43d599e5 320 $self->z(0);
26fbace8 321 };
2c0cbef7 322
fcd84ca9 323=head1 DESCRIPTION
324
26fbace8 325Moose is an extension of the Perl 5 object system.
e522431d 326
9b9da6f1 327The main goal of Moose is to make Perl 5 Object Oriented programming
328easier, more consistent and less tedious. With Moose you can to think
6f894f30 329more about what you want to do and less about the mechanics of OOP.
fcd84ca9 330
6f894f30 331Additionally, Moose is built on top of L<Class::MOP>, which is a
332metaclass system for Perl 5. This means that Moose not only makes
333building normal Perl 5 objects better, but it provides the power of
334metaclass programming as well.
8bdc7f13 335
f5909dca 336=head2 New to Moose?
337
60eccd1e 338If you're new to Moose, the best place to start is the
339L<Moose::Manual> docs, followed by the L<Moose::Cookbook>. The intro
340will show you what Moose is, and how it makes Perl 5 OO better.
6f894f30 341
342The cookbook recipes on Moose basics will get you up to speed with
343many of Moose's features quickly. Once you have an idea of what Moose
344can do, you can use the API documentation to get more detail on
345features which interest you.
f5909dca 346
28669f89 347=head2 Moose Extensions
348
12aed9a0 349The C<MooseX::> namespace is the official place to find Moose extensions.
350These extensions can be found on the CPAN. The easiest way to find them
351is to search for them (L<http://search.cpan.org/search?query=MooseX::>),
352or to examine L<Task::Moose> which aims to keep an up-to-date, easily
353installable list of Moose extensions.
28669f89 354
ceb61b4f 355=head1 TRANSLATIONS
356
357Much of the Moose documentation has been translated into other languages.
358
359=over 4
360
52a0d29a 361=item Japanese
362
45902e41 363Japanese docs can be found at
364L<http://perldoc.perlassociation.org/pod/Moose-Doc-JA/index.html>. The
365source POD files can be found in GitHub:
366L<http://github.com/jpa/Moose-Doc-JA>
ceb61b4f 367
368=back
369
6ba6d68c 370=head1 BUILDING CLASSES WITH MOOSE
371
68efb014 372Moose makes every attempt to provide as much convenience as possible during
373class construction/definition, but still stay out of your way if you want it
374to. Here are a few items to note when building classes with Moose.
6ba6d68c 375
26fbace8 376Unless specified with C<extends>, any class which uses Moose will
6ba6d68c 377inherit from L<Moose::Object>.
378
1cd45431 379Moose will also manage all attributes (including inherited ones) that are
380defined with C<has>. And (assuming you call C<new>, which is inherited from
381L<Moose::Object>) this includes properly initializing all instance slots,
382setting defaults where appropriate, and performing any type constraint checking
383or coercion.
6ba6d68c 384
004222dc 385=head1 PROVIDED METHODS
6ba6d68c 386
d03bd989 387Moose provides a number of methods to all your classes, mostly through the
004222dc 388inheritance of L<Moose::Object>. There is however, one exception.
6ba6d68c 389
390=over 4
391
392=item B<meta>
393
394This is a method which provides access to the current class's metaclass.
395
004222dc 396=back
397
398=head1 EXPORTED FUNCTIONS
399
400Moose will export a number of functions into the class's namespace which
401may then be used to set up the class. These functions all work directly
402on the current class.
403
404=over 4
405
6ba6d68c 406=item B<extends (@superclasses)>
407
408This function will set the superclass(es) for the current class.
409
26fbace8 410This approach is recommended instead of C<use base>, because C<use base>
411actually C<push>es onto the class's C<@ISA>, whereas C<extends> will
412replace it. This is important to ensure that classes which do not have
68efb014 413superclasses still properly inherit from L<Moose::Object>.
6ba6d68c 414
2e7f6cf4 415Each superclass can be followed by a hash reference with options. Currently,
416only L<-version|Class::MOP/Class Loading Options> is recognized:
417
418 extends 'My::Parent' => { -version => 0.01 },
419 'My::OtherParent' => { -version => 0.03 };
420
421An exception will be thrown if the version requirements are not
422satisfied.
423
43d599e5 424=item B<with (@roles)>
e9ec68d6 425
d03bd989 426This will apply a given set of C<@roles> to the local class.
e9ec68d6 427
2e7f6cf4 428Like with C<extends>, each specified role can be followed by a hash
429reference with a L<-version|Class::MOP/Class Loading Options> option:
430
431 with 'My::Role' => { -version => 0.32 },
432 'My::Otherrole' => { -version => 0.23 };
433
434The specified version requirements must be satisfied, otherwise an
435exception will be thrown.
436
437If your role takes options or arguments, they can be passed along in the
438hash reference as well.
439
b4291ab4 440=item B<has $name|@$names =E<gt> %options>
6ba6d68c 441
b4291ab4 442This will install an attribute of a given C<$name> into the current class. If
443the first parameter is an array reference, it will create an attribute for
444every C<$name> in the list. The C<%options> are the same as those provided by
445L<Class::MOP::Attribute>, in addition to the list below which are provided by
446Moose (L<Moose::Meta::Attribute> to be more specific):
6ba6d68c 447
448=over 4
449
076c81ed 450=item I<is =E<gt> 'rw'|'ro'>
6ba6d68c 451
26fbace8 452The I<is> option accepts either I<rw> (for read/write) or I<ro> (for read
453only). These will create either a read/write accessor or a read-only
6ba6d68c 454accessor respectively, using the same name as the C<$name> of the attribute.
455
1b46b845 456If you need more control over how your accessors are named, you can
457use the L<reader|Class::MOP::Attribute/reader>,
458L<writer|Class::MOP::Attribute/writer> and
459L<accessor|Class::MOP::Attribute/accessor> options inherited from
460L<Class::MOP::Attribute>, however if you use those, you won't need the
461I<is> option.
6ba6d68c 462
076c81ed 463=item I<isa =E<gt> $type_name>
6ba6d68c 464
26fbace8 465The I<isa> option uses Moose's type constraint facilities to set up runtime
466type checking for this attribute. Moose will perform the checks during class
467construction, and within any accessors. The C<$type_name> argument must be a
468string. The string may be either a class name or a type defined using
9cca2e9e 469Moose's type definition features. (Refer to L<Moose::Util::TypeConstraints>
c2a69ef1 470for information on how to define a new type, and how to retrieve type meta-data).
6ba6d68c 471
daea75c9 472=item I<coerce =E<gt> (1|0)>
473
26fbace8 474This will attempt to use coercion with the supplied type constraint to change
475the value passed into any accessors or constructors. You B<must> have supplied
5cfe3805 476a type constraint in order for this to work. See L<Moose::Cookbook::Basics::Recipe5>
1cd45431 477for an example.
daea75c9 478
479=item I<does =E<gt> $role_name>
480
26fbace8 481This will accept the name of a role which the value stored in this attribute
daea75c9 482is expected to have consumed.
483
484=item I<required =E<gt> (1|0)>
485
81bec8f8 486This marks the attribute as being required. This means a value must be
be1355c0 487supplied during class construction, I<or> the attribute must be lazy
488and have either a default or a builder. Note that c<required> does not
489say anything about the attribute's value, which can be C<undef>.
daea75c9 490
491=item I<weak_ref =E<gt> (1|0)>
492
68efb014 493This will tell the class to store the value of this attribute as a weakened
494reference. If an attribute is a weakened reference, it B<cannot> also be
495coerced.
daea75c9 496
497=item I<lazy =E<gt> (1|0)>
498
26fbace8 499This will tell the class to not create this slot until absolutely necessary.
daea75c9 500If an attribute is marked as lazy it B<must> have a default supplied.
501
9e93dd19 502=item I<auto_deref =E<gt> (1|0)>
503
1668f3d7 504This tells the accessor to automatically dereference the value of this
505attribute when called in list context. The accessor will still return a
606cc2a6 506reference when called in scalar context. If this behavior isn't desirable,
507L<Moose::Meta::Attribute::Native::Trait::Array/elements> or
508L<Moose::Meta::Attribute::Native::Trait::Hash/elements> may be a better
509choice. The I<auto_deref> option is only legal if your I<isa> option is
510either C<ArrayRef> or C<HashRef>.
9e93dd19 511
65e14c86 512=item I<trigger =E<gt> $code>
513
525129a5 514The I<trigger> option is a CODE reference which will be called after
c25ca3a6 515the value of the attribute is set. The CODE ref is passed the
516instance itself, the updated value, and the original value if the
517attribute was already set.
3dda07f5 518
519You B<can> have a trigger on a read-only attribute.
010997ca 520
521B<NOTE:> Triggers will only fire when you B<assign> to the attribute,
522either in the constructor, or using the writer. Default and built values will
523B<not> cause the trigger to be fired.
daea75c9 524
c7761602 525=item I<handles =E<gt> ARRAY | HASH | REGEXP | ROLE | ROLETYPE | DUCKTYPE | CODE>
2c0cbef7 526
26fbace8 527The I<handles> option provides Moose classes with automated delegation features.
528This is a pretty complex and powerful option. It accepts many different option
529formats, each with its own benefits and drawbacks.
38e3283b 530
1cd45431 531B<NOTE:> The class being delegated to does not need to be a Moose based class,
532which is why this feature is especially useful when wrapping non-Moose classes.
38e3283b 533
1cd45431 534All I<handles> option formats share the following traits:
38e3283b 535
1cd45431 536You cannot override a locally defined method with a delegated method; an
537exception will be thrown if you try. That is to say, if you define C<foo> in
538your class, you cannot override it with a delegated C<foo>. This is almost never
539something you would want to do, and if it is, you should do it by hand and not
540use Moose.
38e3283b 541
1cd45431 542You cannot override any of the methods found in Moose::Object, or the C<BUILD>
543and C<DEMOLISH> methods. These will not throw an exception, but will silently
544move on to the next method in the list. My reasoning for this is that you would
545almost never want to do this, since it usually breaks your class. As with
546overriding locally defined methods, if you do want to do this, you should do it
547manually, not with Moose.
38e3283b 548
d03bd989 549You do not I<need> to have a reader (or accessor) for the attribute in order
550to delegate to it. Moose will create a means of accessing the value for you,
551however this will be several times B<less> efficient then if you had given
f3c4e20e 552the attribute a reader (or accessor) to use.
553
38e3283b 554Below is the documentation for each option format:
555
556=over 4
557
558=item C<ARRAY>
559
26fbace8 560This is the most common usage for I<handles>. You basically pass a list of
561method names to be delegated, and Moose will install a delegation method
1cd45431 562for each one.
38e3283b 563
564=item C<HASH>
565
26fbace8 566This is the second most common usage for I<handles>. Instead of a list of
567method names, you pass a HASH ref where each key is the method name you
568want installed locally, and its value is the name of the original method
569in the class being delegated to.
fd595040 570
26fbace8 571This can be very useful for recursive classes like trees. Here is a
5cfe3805 572quick example (soon to be expanded into a Moose::Cookbook recipe):
38e3283b 573
1cd45431 574 package Tree;
38e3283b 575 use Moose;
26fbace8 576
38e3283b 577 has 'node' => (is => 'rw', isa => 'Any');
26fbace8 578
38e3283b 579 has 'children' => (
580 is => 'ro',
581 isa => 'ArrayRef',
582 default => sub { [] }
583 );
26fbace8 584
38e3283b 585 has 'parent' => (
586 is => 'rw',
587 isa => 'Tree',
a4e516f6 588 weak_ref => 1,
38e3283b 589 handles => {
590 parent_node => 'node',
26fbace8 591 siblings => 'children',
38e3283b 592 }
593 );
594
1cd45431 595In this example, the Tree package gets C<parent_node> and C<siblings> methods,
596which delegate to the C<node> and C<children> methods (respectively) of the Tree
26fbace8 597instance stored in the C<parent> slot.
38e3283b 598
9218b114 599You may also use an array reference to curry arguments to the original method.
600
601 has 'thing' => (
602 ...
3c573ca4 603 handles => { set_foo => [ set => 'foo' ] },
9218b114 604 );
605
606 # $self->set_foo(...) calls $self->thing->set('foo', ...)
607
608The first element of the array reference is the original method name, and the
3c573ca4 609rest is a list of curried arguments.
9218b114 610
38e3283b 611=item C<REGEXP>
612
26fbace8 613The regexp option works very similar to the ARRAY option, except that it builds
614the list of methods for you. It starts by collecting all possible methods of the
615class being delegated to, then filters that list using the regexp supplied here.
38e3283b 616
26fbace8 617B<NOTE:> An I<isa> option is required when using the regexp option format. This
618is so that we can determine (at compile time) the method list from the class.
38e3283b 619Without an I<isa> this is just not possible.
620
c7761602 621=item C<ROLE> or C<ROLETYPE>
c84f324f 622
c7761602 623With the role option, you specify the name of a role or a
624L<role type|Moose::Meta::TypeConstraint::Role> whose "interface" then becomes
625the list of methods to handle. The "interface" can be defined as; the methods
626of the role and any required methods of the role. It should be noted that this
627does B<not> include any method modifiers or generated attribute methods (which
628is consistent with role composition).
c84f324f 629
e3de240e 630=item C<DUCKTYPE>
631
a6d8545f 632With the duck type option, you pass a duck type object whose "interface" then
633becomes the list of methods to handle. The "interface" can be defined as; the
634list of methods passed to C<duck_type> to create a duck type object. For more
635information on C<duck_type> please check
e9c2746e 636L<Moose::Util::TypeConstraints>.
e3de240e 637
38e3283b 638=item C<CODE>
639
1cd45431 640This is the option to use when you really want to do something funky. You should
641only use it if you really know what you are doing, as it involves manual
642metaclass twiddling.
38e3283b 643
1cd45431 644This takes a code reference, which should expect two arguments. The first is the
645attribute meta-object this I<handles> is attached to. The second is the
646metaclass of the class being delegated to. It expects you to return a hash (not
26fbace8 647a HASH ref) of the methods you want mapped.
38e3283b 648
649=back
2c0cbef7 650
004222dc 651=item I<metaclass =E<gt> $metaclass_name>
652
653This tells the class to use a custom attribute metaclass for this particular
654attribute. Custom attribute metaclasses are useful for extending the
655capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
d03bd989 656but they are still a fairly advanced topic and too much to cover here, see
5cfe3805 657L<Moose::Cookbook::Meta::Recipe1> for more information.
004222dc 658
8a8856de 659See L<Metaclass and Trait Name Resolution> for details on how a metaclass name
660is resolved to a class name.
004222dc 661
662=item I<traits =E<gt> [ @role_names ]>
663
d03bd989 664This tells Moose to take the list of C<@role_names> and apply them to the
665attribute meta-object. This is very similar to the I<metaclass> option, but
54f2996d 666allows you to use more than one extension at a time.
004222dc 667
8a8856de 668See L<Metaclass and Trait Name Resolution> for details on how a trait name is
669resolved to a role name.
54f2996d 670
671Also see L<Moose::Cookbook::Meta::Recipe3> for a metaclass trait
672example.
004222dc 673
019f031d 674=item I<builder> => Str
010997ca 675
1b46b845 676The value of this key is the name of the method that will be called to
677obtain the value used to initialize the attribute. See the L<builder
678option docs in Class::MOP::Attribute|Class::MOP::Attribute/builder>
0bb2cc8a 679 and/or L<Moose::Cookbook::Basics::Recipe8> for more information.
010997ca 680
019f031d 681=item I<default> => SCALAR | CODE
010997ca 682
683The value of this key is the default value which will initialize the attribute.
684
1b46b845 685NOTE: If the value is a simple scalar (string or number), then it can
686be just passed as is. However, if you wish to initialize it with a
687HASH or ARRAY ref, then you need to wrap that inside a CODE reference.
688See the L<default option docs in
689Class::MOP::Attribute|Class::MOP::Attribute/default> for more
690information.
010997ca 691
019f031d 692=item I<clearer> => Str
010997ca 693
afd72e0c 694Creates a method allowing you to clear the value, see the L<clearer option
695docs in Class::MOP::Attribute|Class::MOP::Attribute/clearer> for more
1b46b845 696information.
010997ca 697
019f031d 698=item I<predicate> => Str
010997ca 699
afd72e0c 700Creates a method to perform a basic test to see if a value has been set in the
701attribute, see the L<predicate option docs in
702Class::MOP::Attribute|Class::MOP::Attribute/predicate> for more information.
010997ca 703
019f031d 704=item I<lazy_build> => (0|1)
705
706Automatically define lazy => 1 as well as builder => "_build_$attr", clearer =>
707"clear_$attr', predicate => 'has_$attr' unless they are already defined.
708
8c63a5c8 709=item I<initializer> => Str
710
711This may be a method name (referring to a method on the class with
712this attribute) or a CODE ref. The initializer is used to set the
713attribute value on an instance when the attribute is set during
714instance initialization (but not when the value is being assigned
715to). See the L<initializer option docs in
716Class::MOP::Attribute|Class::MOP::Attribute/initializer> for more
717information.
019f031d 718
60dcf673 719=item I<documentation> => $string
720
721An arbitrary string that can be retrieved later by calling C<<
722$attr->documentation >>.
723
724
725
6ba6d68c 726=back
727
cd7eeaf5 728=item B<has +$name =E<gt> %options>
729
c7874946 730This is variation on the normal attribute creator C<has> which allows you to
d03bd989 731clone and extend an attribute from a superclass or from a role. Here is an
8d62bf6d 732example of the superclass usage:
cd7eeaf5 733
734 package Foo;
735 use Moose;
26fbace8 736
cd7eeaf5 737 has 'message' => (
26fbace8 738 is => 'rw',
cd7eeaf5 739 isa => 'Str',
740 default => 'Hello, I am a Foo'
741 );
26fbace8 742
cd7eeaf5 743 package My::Foo;
744 use Moose;
26fbace8 745
cd7eeaf5 746 extends 'Foo';
26fbace8 747
cd7eeaf5 748 has '+message' => (default => 'Hello I am My::Foo');
749
1cd45431 750What is happening here is that B<My::Foo> is cloning the C<message> attribute
751from its parent class B<Foo>, retaining the C<is =E<gt> 'rw'> and C<isa =E<gt>
752'Str'> characteristics, but changing the value in C<default>.
cd7eeaf5 753
8d62bf6d 754Here is another example, but within the context of a role:
755
756 package Foo::Role;
757 use Moose::Role;
986d175a 758
8d62bf6d 759 has 'message' => (
760 is => 'rw',
761 isa => 'Str',
762 default => 'Hello, I am a Foo'
763 );
986d175a 764
8d62bf6d 765 package My::Foo;
766 use Moose;
986d175a 767
8d62bf6d 768 with 'Foo::Role';
986d175a 769
8d62bf6d 770 has '+message' => (default => 'Hello I am My::Foo');
771
d03bd989 772In this case, we are basically taking the attribute which the role supplied
773and altering it within the bounds of this feature.
8d62bf6d 774
73f70bdf 775Note that you can only extend an attribute from either a superclass or a role,
776you cannot extend an attribute in a role that composes over an attribute from
777another role.
778
d03bd989 779Aside from where the attributes come from (one from superclass, the other
780from a role), this feature works exactly the same. This feature is restricted
781somewhat, so as to try and force at least I<some> sanity into it. You are only
4032c9bb 782allowed to change the following attributes:
cd7eeaf5 783
784=over 4
785
26fbace8 786=item I<default>
cd7eeaf5 787
788Change the default value of an attribute.
789
26fbace8 790=item I<coerce>
cd7eeaf5 791
792Change whether the attribute attempts to coerce a value passed to it.
793
26fbace8 794=item I<required>
cd7eeaf5 795
796Change if the attribute is required to have a value.
797
798=item I<documentation>
799
800Change the documentation string associated with the attribute.
801
83cc9094 802=item I<lazy>
803
804Change if the attribute lazily initializes the slot.
805
cd7eeaf5 806=item I<isa>
807
d03bd989 808You I<are> allowed to change the type without restriction.
aed87761 809
d03bd989 810It is recommended that you use this freedom with caution. We used to
811only allow for extension only if the type was a subtype of the parent's
812type, but we felt that was too restrictive and is better left as a
813policy decision.
cd7eeaf5 814
83cc9094 815=item I<handles>
816
26fbace8 817You are allowed to B<add> a new C<handles> definition, but you are B<not>
818allowed to I<change> one.
83cc9094 819
8d62bf6d 820=item I<builder>
821
822You are allowed to B<add> a new C<builder> definition, but you are B<not>
823allowed to I<change> one.
824
13284479 825=item I<metaclass>
826
827You are allowed to B<add> a new C<metaclass> definition, but you are
828B<not> allowed to I<change> one.
829
830=item I<traits>
831
832You are allowed to B<add> additional traits to the C<traits> definition.
6549b0d1 833These traits will be composed into the attribute, but preexisting traits
13284479 834B<are not> overridden, or removed.
835
cd7eeaf5 836=back
837
78946cf8 838=item B<before $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
6ba6d68c 839
78946cf8 840=item B<after $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
6ba6d68c 841
78946cf8 842=item B<around $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
6ba6d68c 843
e9f7d5c5 844These three items are syntactic sugar for the before, after, and around method
d8af92ae 845modifier features that L<Class::MOP> provides. More information on these may be
9b75e4b6 846found in L<Moose::Manual::MethodModifiers> and the
847L<Class::MOP::Class documentation|Class::MOP::Class/"Method Modifiers">.
6ba6d68c 848
159da176 849=item B<super>
850
26fbace8 851The keyword C<super> is a no-op when called outside of an C<override> method. In
852the context of an C<override> method, it will call the next most appropriate
159da176 853superclass method with the same arguments as the original method.
854
855=item B<override ($name, &sub)>
856
26fbace8 857An C<override> method is a way of explicitly saying "I am overriding this
858method from my superclass". You can call C<super> within this method, and
859it will work as expected. The same thing I<can> be accomplished with a normal
860method call and the C<SUPER::> pseudo-package; it is really your choice.
159da176 861
862=item B<inner>
863
26fbace8 864The keyword C<inner>, much like C<super>, is a no-op outside of the context of
865an C<augment> method. You can think of C<inner> as being the inverse of
68efb014 866C<super>; the details of how C<inner> and C<augment> work is best described in
5cfe3805 867the L<Moose::Cookbook::Basics::Recipe6>.
159da176 868
869=item B<augment ($name, &sub)>
870
26fbace8 871An C<augment> method, is a way of explicitly saying "I am augmenting this
872method from my superclass". Once again, the details of how C<inner> and
5cfe3805 873C<augment> work is best described in the L<Moose::Cookbook::Basics::Recipe6>.
159da176 874
6ba6d68c 875=item B<confess>
876
68efb014 877This is the C<Carp::confess> function, and exported here because I use it
d03bd989 878all the time.
6ba6d68c 879
880=item B<blessed>
881
1cd45431 882This is the C<Scalar::Util::blessed> function, it is exported here because I
26fbace8 883use it all the time. It is highly recommended that this is used instead of
6ba6d68c 884C<ref> anywhere you need to test for an object's class name.
885
886=back
887
c1381000 888=head1 METACLASS
54f2996d 889
c1381000 890When you use Moose, you can specify which metaclass to use:
891
892 use Moose -metaclass => 'My::Meta::Class';
893
894You can also specify traits which will be applied to your metaclass:
54f2996d 895
896 use Moose -traits => 'My::Trait';
897
898This is very similar to the attribute traits feature. When you do
899this, your class's C<meta> object will have the specified traits
8a8856de 900applied to it. See L<Metaclass and Trait Name Resolution> for more
901details.
54f2996d 902
8a8856de 903=head2 Metaclass and Trait Name Resolution
54f2996d 904
905By default, when given a trait name, Moose simply tries to load a
906class of the same name. If such a class does not exist, it then looks
907for for a class matching
908B<Moose::Meta::$type::Custom::Trait::$trait_name>. The C<$type>
909variable here will be one of B<Attribute> or B<Class>, depending on
910what the trait is being applied to.
911
912If a class with this long name exists, Moose checks to see if it has
913the method C<register_implementation>. This method is expected to
914return the I<real> class name of the trait. If there is no
915C<register_implementation> method, it will fall back to using
916B<Moose::Meta::$type::Custom::Trait::$trait> as the trait name.
917
8a8856de 918The lookup method for metaclasses is the same, except that it looks
919for a class matching B<Moose::Meta::$type::Custom::$metaclass_name>.
920
54f2996d 921If all this is confusing, take a look at
922L<Moose::Cookbook::Meta::Recipe3>, which demonstrates how to create an
923attribute trait.
924
1cd45431 925=head1 UNIMPORTING FUNCTIONS
31f8ec72 926
927=head2 B<unimport>
928
1cd45431 929Moose offers a way to remove the keywords it exports, through the C<unimport>
31f8ec72 930method. You simply have to say C<no Moose> at the bottom of your code for this
931to work. Here is an example:
932
933 package Person;
934 use Moose;
935
936 has 'first_name' => (is => 'rw', isa => 'Str');
937 has 'last_name' => (is => 'rw', isa => 'Str');
26fbace8 938
939 sub full_name {
31f8ec72 940 my $self = shift;
26fbace8 941 $self->first_name . ' ' . $self->last_name
31f8ec72 942 }
26fbace8 943
944 no Moose; # keywords are removed from the Person package
31f8ec72 945
9bcfbab1 946=head1 EXTENDING AND EMBEDDING MOOSE
947
5e86efbe 948To learn more about extending Moose, we recommend checking out the
949"Extending" recipes in the L<Moose::Cookbook>, starting with
950L<Moose::Cookbook::Extending::Recipe1>, which provides an overview of
951all the different ways you might extend Moose.
554b7648 952
953=head2 B<< Moose->init_meta(for_class => $class, base_class => $baseclass, metaclass => $metaclass) >>
9bcfbab1 954
554b7648 955The C<init_meta> method sets up the metaclass object for the class
b143539e 956specified by C<for_class>. This method injects a a C<meta> accessor
957into the class so you can get at this object. It also sets the class's
554b7648 958superclass to C<base_class>, with L<Moose::Object> as the default.
9bcfbab1 959
a8de959b 960C<init_meta> returns the metaclass object for C<$class>.
961
16fb3624 962You can specify an alternate metaclass with the C<metaclass> option.
26fbace8 963
80837fe1 964For more detail on this topic, see L<Moose::Cookbook::Extending::Recipe2>.
965
554b7648 966This method used to be documented as a function which accepted
967positional parameters. This calling style will still work for
4a66a4b3 968backwards compatibility, but is deprecated.
554b7648 969
970=head2 B<import>
971
972Moose's C<import> method supports the L<Sub::Exporter> form of C<{into =E<gt> $pkg}>
973and C<{into_level =E<gt> 1}>.
974
975B<NOTE>: Doing this is more or less deprecated. Use L<Moose::Exporter>
976instead, which lets you stack multiple C<Moose.pm>-alike modules
977sanely. It handles getting the exported functions into the right place
978for you.
979
23d3fe84 980=head2 B<throw_error>
4c0b3599 981
982An alias for C<confess>, used by internally by Moose.
983
a94f30ac 984=head2 The MooseX:: namespace
985
986Generally if you're writing an extension I<for> Moose itself you'll want
987to put your extension in the C<MooseX::> namespace. This namespace is
988specifically for extensions that make Moose better or different in some
989fundamental way. It is traditionally B<not> for a package that just happens
990to use Moose. This namespace follows from the examples of the C<LWPx::>
991and C<DBIx::> namespaces that perform the same function for C<LWP> and C<DBI>
992respectively.
993
6ea5491a 994=head1 METACLASS COMPATIBILITY AND MOOSE
995
996Metaclass compatibility is a thorny subject. You should start by
997reading the "About Metaclass compatibility" section in the
998C<Class::MOP> docs.
999
1000Moose will attempt to resolve a few cases of metaclass incompatibility
b9216044 1001when you set the superclasses for a class, in addition to the cases that
1002C<Class::MOP> handles.
1003
1004Moose tries to determine if the metaclasses only "differ by roles". This
1005means that the parent and child's metaclass share a common ancestor in
1006their respective hierarchies, and that the subclasses under the common
1007ancestor are only different because of role applications. This case is
1008actually fairly common when you mix and match various C<MooseX::*>
1009modules, many of which apply roles to the metaclass.
6ea5491a 1010
1011If the parent and child do differ by roles, Moose replaces the
1012metaclass in the child with a newly created metaclass. This metaclass
1013is a subclass of the parent's metaclass, does all of the roles that
1014the child's metaclass did before being replaced. Effectively, this
1015means the new metaclass does all of the roles done by both the
1016parent's and child's original metaclasses.
1017
1018Ultimately, this is all transparent to you except in the case of an
1019unresolvable conflict.
1020
05d9eaf6 1021=head1 CAVEATS
1022
1023=over 4
1024
1025=item *
1026
1cd45431 1027It should be noted that C<super> and C<inner> B<cannot> be used in the same
1028method. However, they may be combined within the same class hierarchy; see
1029F<t/014_override_augment_inner_super.t> for an example.
05d9eaf6 1030
26fbace8 1031The reason for this is that C<super> is only valid within a method
1032with the C<override> modifier, and C<inner> will never be valid within an
1033C<override> method. In fact, C<augment> will skip over any C<override> methods
68efb014 1034when searching for its appropriate C<inner>.
05d9eaf6 1035
1cd45431 1036This might seem like a restriction, but I am of the opinion that keeping these
1037two features separate (yet interoperable) actually makes them easy to use, since
1038their behavior is then easier to predict. Time will tell whether I am right or
c84f324f 1039not (UPDATE: so far so good).
05d9eaf6 1040
9b9da6f1 1041=back
1042
e49c11d2 1043=head1 GETTING HELP
1044
1045We offer both a mailing list and a very active IRC channel.
1046
1047The mailing list is L<moose@perl.org>. You must be subscribed to send
1048a message. To subscribe, send an empty message to
1049L<moose-subscribe@perl.org>
1050
236b8a02 1051You can also visit us at C<#moose> on L<irc://irc.perl.org/#moose>
60cbb35f 1052This channel is quite active, and questions at all levels (on Moose-related
1053topics ;) are welcome.
e49c11d2 1054
5569c072 1055=head1 ACKNOWLEDGEMENTS
1056
1057=over 4
1058
54c189df 1059=item I blame Sam Vilain for introducing me to the insanity that is meta-models.
5569c072 1060
54c189df 1061=item I blame Audrey Tang for then encouraging my meta-model habit in #perl6.
5569c072 1062
26fbace8 1063=item Without Yuval "nothingmuch" Kogman this module would not be possible,
54c189df 1064and it certainly wouldn't have this name ;P
5569c072 1065
26fbace8 1066=item The basis of the TypeContraints module was Rob Kinyon's idea
5569c072 1067originally, I just ran with it.
1068
638585e1 1069=item Thanks to mst & chansen and the whole #moose posse for all the
c84f324f 1070early ideas/feature-requests/encouragement/bug-finding.
d46a48f3 1071
68efb014 1072=item Thanks to David "Theory" Wheeler for meta-discussions and spelling fixes.
1073
5569c072 1074=back
1075
e90c03d0 1076=head1 SEE ALSO
1077
1078=over 4
1079
c84f324f 1080=item L<http://www.iinteractive.com/moose>
1081
6d137156 1082This is the official web home of Moose, it contains links to our public git repository
26fbace8 1083as well as links to a number of talks and articles on Moose and Moose related
1084technologies.
c84f324f 1085
196064ab 1086=item The Moose is flying, a tutorial by Randal Schwartz
1087
1088Part 1 - L<http://www.stonehenge.com/merlyn/LinuxMag/col94.html>
1089
1090Part 2 - L<http://www.stonehenge.com/merlyn/LinuxMag/col95.html>
1091
12aed9a0 1092=item Several Moose extension modules in the C<MooseX::> namespace.
1093
1094See L<http://search.cpan.org/search?query=MooseX::> for extensions.
28669f89 1095
e49c11d2 1096=item Moose stats on ohloh.net - L<http://www.ohloh.net/projects/moose>
1097
c84f324f 1098=back
1099
004222dc 1100=head2 Books
1101
1102=over 4
1103
1104=item The Art of the MetaObject Protocol
1105
d03bd989 1106I mention this in the L<Class::MOP> docs too, this book was critical in
004222dc 1107the development of both modules and is highly recommended.
1108
1109=back
1110
26fbace8 1111=head2 Papers
c84f324f 1112
1113=over 4
e90c03d0 1114
159da176 1115=item L<http://www.cs.utah.edu/plt/publications/oopsla04-gff.pdf>
1116
26fbace8 1117This paper (suggested by lbr on #moose) was what lead to the implementation
1118of the C<super>/C<override> and C<inner>/C<augment> features. If you really
1cd45431 1119want to understand them, I suggest you read this.
159da176 1120
e90c03d0 1121=back
1122
fcd84ca9 1123=head1 BUGS
1124
26fbace8 1125All complex software has bugs lurking in it, and this module is no
7efc4307 1126exception.
1127
1128Please report any bugs to C<bug-moose@rt.cpan.org>, or through the web
1129interface at L<http://rt.cpan.org>.
fcd84ca9 1130
0334ee02 1131You can also discuss feature requests or possible bugs on the Moose mailing
1132list (moose@perl.org) or on IRC at L<irc://irc.perl.org/#moose>.
1133
47b19570 1134=head1 FEATURE REQUESTS
1135
d03bd989 1136We are very strict about what features we add to the Moose core, especially
1137the user-visible features. Instead we have made sure that the underlying
1138meta-system of Moose is as extensible as possible so that you can add your
854b298d 1139own features easily.
1140
1141That said, occasionally there is a feature needed in the meta-system
1142to support your planned extension, in which case you should either
1143email the mailing list (moose@perl.org) or join us on IRC at
1144L<irc://irc.perl.org/#moose> to discuss. The
1145L<Moose::Manual::Contributing> has more detail about how and when you
1146can contribute.
47b19570 1147
fcd84ca9 1148=head1 AUTHOR
1149
d03bd989 1150Moose is an open project, there are at this point dozens of people who have
1151contributed, and can contribute. If you have added anything to the Moose
862ae2c4 1152project you have a commit bit on this file and can add your name to the list.
fcd84ca9 1153
862ae2c4 1154=head2 CABAL
1155
d03bd989 1156However there are only a few people with the rights to release a new version
862ae2c4 1157of Moose. The Moose Cabal are the people to go to with questions regarding
a4869d1e 1158the wider purview of Moose, and help out maintaining not just the code
958dc4e3 1159but the community as well.
862ae2c4 1160
1161Stevan (stevan) Little E<lt>stevan@iinteractive.comE<gt>
1162
2a267bff 1163Jesse (doy) Luehrs E<lt>doy at tozt dot netE<gt>
1164
862ae2c4 1165Yuval (nothingmuch) Kogman
1166
69ba075f 1167Shawn (sartak) Moore E<lt>sartak@bestpractical.comE<gt>
862ae2c4 1168
fd995afb 1169Hans Dieter (confound) Pearcey E<lt>hdp@pobox.comE<gt>
1170
d209e3ad 1171Chris (perigrin) Prather
1172
36edf31b 1173Florian Ragwitz E<lt>rafl@debian.orgE<gt>
d209e3ad 1174
2a267bff 1175Dave (autarch) Rolsky E<lt>autarch@urth.orgE<gt>
1176
862ae2c4 1177=head2 OTHER CONTRIBUTORS
db1ab48d 1178
9af1d28b 1179Aankhen
1180
1181Adam (Alias) Kennedy
1182
1183Anders (Debolaz) Nor Berle
1184
6549b0d1 1185Nathan (kolibrie) Gray
5868294f 1186
9af1d28b 1187Christian (chansen) Hansen
1188
1189Eric (ewilhelm) Wilhelm
1190
1191Guillermo (groditi) Roditi
1192
1193Jess (castaway) Robinson
1194
1195Matt (mst) Trout
1196
1197Robert (phaylon) Sedlacek
1198
1199Robert (rlb3) Boone
1200
1201Scott (konobi) McWhirter
1202
f44ae52f 1203Shlomi (rindolf) Fish
1204
68b6146c 1205Wallace (wreis) Reis
1206
e46f5cc2 1207Jonathan (jrockway) Rockway
1208
3ccdc84a 1209Piotr (dexter) Roszatycki
1210
26fbace8 1211Sam (mugwump) Vilain
f1917f58 1212
2f7e4042 1213Cory (gphat) Watson
1214
0be258b5 1215Dylan Hardison (doc fixes)
1216
9af1d28b 1217... and many other #moose folks
98aae381 1218
fcd84ca9 1219=head1 COPYRIGHT AND LICENSE
1220
7e0492d3 1221Copyright 2006-2010 by Infinity Interactive, Inc.
fcd84ca9 1222
1223L<http://www.iinteractive.com>
1224
1225This library is free software; you can redistribute it and/or modify
26fbace8 1226it under the same terms as Perl itself.
fcd84ca9 1227
ddd0ec20 1228=cut