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