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