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