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