X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose.pm;h=e80b5232388d2c3d5922cb148449181ee4ae94fa;hb=d67398abd3303d2fb8ed67d78313a202dec7283b;hp=44dc9e9b1ef45cdae7c1e505e6869ecdda68db7b;hpb=8a8856dedc0c13a38701fff0d9b8c1c2bef2a4a8;p=gitmo%2FMoose.git diff --git a/lib/Moose.pm b/lib/Moose.pm index 44dc9e9..e80b523 100644 --- a/lib/Moose.pm +++ b/lib/Moose.pm @@ -4,16 +4,17 @@ use warnings; use 5.008; -our $VERSION = '0.88'; +our $VERSION = '1.14'; $VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; use Scalar::Util 'blessed'; use Carp 'confess'; +use Moose::Deprecated; use Moose::Exporter; -use Class::MOP 0.89; +use Class::MOP 1.08; use Moose::Meta::Class; use Moose::Meta::TypeConstraint; @@ -34,6 +35,8 @@ use Moose::Meta::Role::Application::ToInstance; use Moose::Util::TypeConstraints; use Moose::Util (); +use Moose::Meta::Attribute::Native; + sub throw_error { # FIXME This shift; @@ -41,46 +44,42 @@ sub throw_error { } sub extends { - my $class = shift; + my $meta = shift; Moose->throw_error("Must derive at least one class") unless @_; # this checks the metaclass to make sure # it is correct, sometimes it can get out # of sync when the classes are being built - Moose::Meta::Class->initialize($class)->superclasses(@_); + $meta->superclasses(@_); } sub with { - my $class = shift; - Moose::Util::apply_all_roles(Class::MOP::Class->initialize($class), @_); + Moose::Util::apply_all_roles(shift, @_); } sub has { - my $class = shift; - my $name = shift; + my $meta = shift; + my $name = shift; Moose->throw_error('Usage: has \'name\' => ( key => value, ... )') if @_ % 2 == 1; my %options = ( definition_context => Moose::Util::_caller_info(), @_ ); my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ]; - Class::MOP::Class->initialize($class)->add_attribute( $_, %options ) for @$attrs; + $meta->add_attribute( $_, %options ) for @$attrs; } sub before { - my $class = shift; - Moose::Util::add_method_modifier($class, 'before', \@_); + Moose::Util::add_method_modifier(shift, 'before', \@_); } sub after { - my $class = shift; - Moose::Util::add_method_modifier($class, 'after', \@_); + Moose::Util::add_method_modifier(shift, 'after', \@_); } sub around { - my $class = shift; - Moose::Util::add_method_modifier($class, 'around', \@_); + Moose::Util::add_method_modifier(shift, 'around', \@_); } our $SUPER_PACKAGE; @@ -95,9 +94,9 @@ sub super { } sub override { - my $class = shift; + my $meta = shift; my ( $name, $method ) = @_; - Class::MOP::Class->initialize($class)->add_override_method_modifier( $name => $method ); + $meta->add_override_method_modifier( $name => $method ); } sub inner { @@ -115,14 +114,14 @@ sub inner { } sub augment { - my $class = shift; + my $meta = shift; my ( $name, $method ) = @_; - Class::MOP::Class->initialize($class)->add_augment_method_modifier( $name => $method ); + $meta->add_augment_method_modifier( $name => $method ); } Moose::Exporter->setup_import_methods( - with_caller => [ - qw( extends with has before after around override augment) + with_meta => [ + qw( extends with has before after around override augment ) ], as_is => [ qw( super inner ), @@ -135,6 +134,11 @@ sub init_meta { # This used to be called as a function. This hack preserves # backwards compatibility. if ( $_[0] ne __PACKAGE__ ) { + Moose::Deprecated::deprecated( + feature => 'Moose::init_meta', + message => 'Calling Moose::init_meta as a function is deprecated', + ); + return __PACKAGE__->init_meta( for_class => $_[0], base_class => $_[1], @@ -161,19 +165,24 @@ sub init_meta { if ( $meta = Class::MOP::get_metaclass_by_name($class) ) { unless ( $meta->isa("Moose::Meta::Class") ) { - Moose->throw_error("$class already has a metaclass, but it does not inherit $metaclass ($meta)"); + my $error_message = "$class already has a metaclass, but it does not inherit $metaclass ($meta)."; + if ( $meta->isa('Moose::Meta::Role') ) { + Moose->throw_error($error_message . ' You cannot make the same thing a role and a class. Remove either Moose or Moose::Role.'); + } else { + Moose->throw_error($error_message); + } } } else { # no metaclass, no 'meta' method # now we check whether our ancestors have metaclass, and if so borrow that - my ( undef, @isa ) = @{ $class->mro::get_linear_isa }; + my ( undef, @isa ) = @{ mro::get_linear_isa($class) }; foreach my $ancestor ( @isa ) { my $ancestor_meta = Class::MOP::get_metaclass_by_name($ancestor) || next; my $ancestor_meta_class = ($ancestor_meta->is_immutable - ? $ancestor_meta->get_mutable_metaclass_name + ? $ancestor_meta->_get_mutable_metaclass_name : ref($ancestor_meta)); # if we have an ancestor metaclass that inherits $metaclass, we use @@ -256,6 +265,7 @@ $_->make_immutable( Moose::Meta::Method::Augmented Moose::Meta::Role + Moose::Meta::Role::Attribute Moose::Meta::Role::Method Moose::Meta::Role::Method::Required Moose::Meta::Role::Method::Conflicting @@ -269,6 +279,11 @@ $_->make_immutable( Moose::Meta::Role::Application::ToInstance ); +Moose::Meta::Mixin::AttributeCore->meta->make_immutable( + inline_constructor => 0, + constructor_name => undef, +); + 1; __END__ @@ -337,14 +352,31 @@ is to search for them (L), or to examine L which aims to keep an up-to-date, easily installable list of Moose extensions. +=head1 TRANSLATIONS + +Much of the Moose documentation has been translated into other languages. + +=over 4 + +=item Japanese + +Japanese docs can be found at +L. The +source POD files can be found in GitHub: +L + +=back + =head1 BUILDING CLASSES WITH MOOSE Moose makes every attempt to provide as much convenience as possible during class construction/definition, but still stay out of your way if you want it to. Here are a few items to note when building classes with Moose. -Unless specified with C, any class which uses Moose will -inherit from L. +When you C, Moose will set the class's parent class to +L, I the class using Moose already has a parent +class. In addition, specifying a parent with C will change the parent +class. Moose will also manage all attributes (including inherited ones) that are defined with C. And (assuming you call C, which is inherited from @@ -382,10 +414,31 @@ actually Ces onto the class's C<@ISA>, whereas C will replace it. This is important to ensure that classes which do not have superclasses still properly inherit from L. +Each superclass can be followed by a hash reference with options. Currently, +only L<-version|Class::MOP/Class Loading Options> is recognized: + + extends 'My::Parent' => { -version => 0.01 }, + 'My::OtherParent' => { -version => 0.03 }; + +An exception will be thrown if the version requirements are not +satisfied. + =item B This will apply a given set of C<@roles> to the local class. +Like with C, each specified role can be followed by a hash +reference with a L<-version|Class::MOP/Class Loading Options> option: + + with 'My::Role' => { -version => 0.32 }, + 'My::Otherrole' => { -version => 0.23 }; + +The specified version requirements must be satisfied, otherwise an +exception will be thrown. + +If your role takes options or arguments, they can be passed along in the +hash reference as well. + =item B %options> This will install an attribute of a given C<$name> into the current class. If @@ -421,9 +474,9 @@ for information on how to define a new type, and how to retrieve type meta-data) =item I (1|0)> This will attempt to use coercion with the supplied type constraint to change -the value passed into any accessors or constructors. You B have supplied -a type constraint in order for this to work. See L -for an example. +the value passed into any accessors or constructors. You B supply a type +constraint, and that type constraint B define a coercion. See +L for an example. =item I $role_name> @@ -450,21 +503,28 @@ If an attribute is marked as lazy it B have a default supplied. =item I (1|0)> -This tells the accessor whether to automatically dereference the value returned. -This is only legal if your C option is either C or C. +This tells the accessor to automatically dereference the value of this +attribute when called in list context. The accessor will still return a +reference when called in scalar context. If this behavior isn't desirable, +L or +L may be a better +choice. The I option is only legal if your I option is +either C or C. =item I $code> The I option is a CODE reference which will be called after -the value of the attribute is set. The CODE ref will be passed the -instance itself and the updated value. You B have a trigger on -a read-only attribute. +the value of the attribute is set. The CODE ref is passed the +instance itself, the updated value, and the original value if the +attribute was already set. + +You B have a trigger on a read-only attribute. B Triggers will only fire when you B to the attribute, either in the constructor, or using the writer. Default and built values will B cause the trigger to be fired. -=item I ARRAY | HASH | REGEXP | ROLE | DUCKTYPE | CODE> +=item I ARRAY | HASH | REGEXP | ROLE | ROLETYPE | DUCKTYPE | CODE> The I option provides Moose classes with automated delegation features. This is a pretty complex and powerful option. It accepts many different option @@ -538,6 +598,18 @@ In this example, the Tree package gets C and C methods, which delegate to the C and C methods (respectively) of the Tree instance stored in the C slot. +You may also use an array reference to curry arguments to the original method. + + has 'thing' => ( + ... + handles => { set_foo => [ set => 'foo' ] }, + ); + + # $self->set_foo(...) calls $self->thing->set('foo', ...) + +The first element of the array reference is the original method name, and the +rest is a list of curried arguments. + =item C The regexp option works very similar to the ARRAY option, except that it builds @@ -548,13 +620,14 @@ B An I option is required when using the regexp option format. This is so that we can determine (at compile time) the method list from the class. Without an I this is just not possible. -=item C +=item C or C -With the role option, you specify the name of a role whose "interface" then -becomes the list of methods to handle. The "interface" can be defined as; the -methods of the role and any required methods of the role. It should be noted -that this does B include any method modifiers or generated attribute -methods (which is consistent with role composition). +With the role option, you specify the name of a role or a +L whose "interface" then becomes +the list of methods to handle. The "interface" can be defined as; the methods +of the role and any required methods of the role. It should be noted that this +does B include any method modifiers or generated attribute methods (which +is consistent with role composition). =item C @@ -605,7 +678,7 @@ example. The value of this key is the name of the method that will be called to obtain the value used to initialize the attribute. See the L - and/or L for more information. + and/or L for more information. =item I => SCALAR | CODE @@ -764,16 +837,16 @@ B overridden, or removed. =back -=item B sub { ... }> +=item B sub { ... }> -=item B sub { ... }> +=item B sub { ... }> -=item B sub { ... }> +=item B sub { ... }> These three items are syntactic sugar for the before, after, and around method modifier features that L provides. More information on these may be -found in the L for now. +found in L and the +L. =item B @@ -910,6 +983,16 @@ for you. An alias for C, used by internally by Moose. +=head2 The MooseX:: namespace + +Generally if you're writing an extension I Moose itself you'll want +to put your extension in the C namespace. This namespace is +specifically for extensions that make Moose better or different in some +fundamental way. It is traditionally B for a package that just happens +to use Moose. This namespace follows from the examples of the C +and C namespaces that perform the same function for C and C +respectively. + =head1 METACLASS COMPATIBILITY AND MOOSE Metaclass compatibility is a thorny subject. You should start by @@ -917,28 +1000,15 @@ reading the "About Metaclass compatibility" section in the C docs. Moose will attempt to resolve a few cases of metaclass incompatibility -when you set the superclasses for a class, unlike C, which -simply dies if the metaclasses are incompatible. +when you set the superclasses for a class, in addition to the cases that +C handles. -In actuality, Moose fixes incompatibility for I of a class's -metaclasses, not just the class metaclass. That includes the instance -metaclass, attribute metaclass, as well as its constructor class and -destructor class. However, for simplicity this discussion will just -refer to "metaclass", meaning the class metaclass, most of the time. - -Moose has two algorithms for fixing metaclass incompatibility. - -The first algorithm is very simple. If all the metaclass for the -parent is a I of the child's metaclass, then we simply -replace the child's metaclass with the parent's. - -The second algorithm is more complicated. It tries to determine if the -metaclasses only "differ by roles". This means that the parent and -child's metaclass share a common ancestor in their respective -hierarchies, and that the subclasses under the common ancestor are -only different because of role applications. This case is actually -fairly common when you mix and match various C modules, -many of which apply roles to the metaclass. +Moose tries to determine if the metaclasses only "differ by roles". This +means that the parent and child's metaclass share a common ancestor in +their respective hierarchies, and that the subclasses under the common +ancestor are only different because of role applications. This case is +actually fairly common when you mix and match various C +modules, many of which apply roles to the metaclass. If the parent and child do differ by roles, Moose replaces the metaclass in the child with a newly created metaclass. This metaclass @@ -950,16 +1020,6 @@ parent's and child's original metaclasses. Ultimately, this is all transparent to you except in the case of an unresolvable conflict. -=head2 The MooseX:: namespace - -Generally if you're writing an extension I Moose itself you'll want -to put your extension in the C namespace. This namespace is -specifically for extensions that make Moose better or different in some -fundamental way. It is traditionally B for a package that just happens -to use Moose. This namespace follows from the examples of the C -and C namespaces that perform the same function for C and C -respectively. - =head1 CAVEATS =over 4 @@ -990,9 +1050,9 @@ The mailing list is L. You must be subscribed to send a message. To subscribe, send an empty message to L -You can also visit us at L<#moose on -irc.perl.org|irc://irc.perl.org/#moose>. This channel is quite active, -and questions at all levels (on Moose-related topics ;) are welcome. +You can also visit us at C<#moose> on L +This channel is quite active, and questions at all levels (on Moose-related +topics ;) are welcome. =head1 ACKNOWLEDGEMENTS @@ -1021,7 +1081,7 @@ early ideas/feature-requests/encouragement/bug-finding. =item L -This is the official web home of Moose, it contains links to our public SVN repository +This is the official web home of Moose, it contains links to our public git repository as well as links to a number of talks and articles on Moose and Moose related technologies. @@ -1070,6 +1130,9 @@ exception. Please report any bugs to C, or through the web interface at L. +You can also discuss feature requests or possible bugs on the Moose mailing +list (moose@perl.org) or on IRC at L. + =head1 FEATURE REQUESTS We are very strict about what features we add to the Moose core, especially @@ -1099,10 +1162,18 @@ but the community as well. Stevan (stevan) Little Estevan@iinteractive.comE +Jesse (doy) Luehrs Edoy at tozt dot netE + Yuval (nothingmuch) Kogman Shawn (sartak) Moore Esartak@bestpractical.comE +Hans Dieter (confound) Pearcey Ehdp@pobox.comE + +Chris (perigrin) Prather + +Florian Ragwitz Erafl@debian.orgE + Dave (autarch) Rolsky Eautarch@urth.orgE =head2 OTHER CONTRIBUTORS @@ -1117,8 +1188,6 @@ Nathan (kolibrie) Gray Christian (chansen) Hansen -Hans Dieter (confound) Pearcey - Eric (ewilhelm) Wilhelm Guillermo (groditi) Roditi @@ -1135,8 +1204,6 @@ Scott (konobi) McWhirter Shlomi (rindolf) Fish -Chris (perigrin) Prather - Wallace (wreis) Reis Jonathan (jrockway) Rockway @@ -1153,7 +1220,7 @@ Dylan Hardison (doc fixes) =head1 COPYRIGHT AND LICENSE -Copyright 2006-2009 by Infinity Interactive, Inc. +Copyright 2006-2010 by Infinity Interactive, Inc. L