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