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