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