use 5.008;
-our $VERSION = '0.98';
+our $VERSION = '1.15';
$VERSION = eval $VERSION;
our $AUTHORITY = 'cpan:STEVAN';
use Scalar::Util 'blessed';
use Carp 'confess';
+use Moose::Deprecated;
use Moose::Exporter;
-use Class::MOP 0.94;
+use Class::MOP 1.10;
use Moose::Meta::Class;
use Moose::Meta::TypeConstraint;
# 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],
or Moose->throw_error("Cannot call init_meta without specifying a for_class");
my $base_class = $args{base_class} || 'Moose::Object';
my $metaclass = $args{metaclass} || 'Moose::Meta::Class';
+ my $meta_name = exists $args{meta_name} ? $args{meta_name} : 'meta';
Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Class.")
unless $metaclass->isa('Moose::Meta::Class');
}
}
} else {
- # no metaclass, no 'meta' method
+ # no metaclass
# 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
- : ref($ancestor_meta));
+ my $ancestor_meta_class = $ancestor_meta->_real_ref_name;
# if we have an ancestor metaclass that inherits $metaclass, we use
# that. This is like _fix_metaclass_incompatibility, but we can do it now.
$meta = $metaclass->initialize($class);
}
- if ( $class->can('meta') ) {
- # check 'meta' method
-
- # it may be inherited
-
- # NOTE:
- # this is the case where the metaclass pragma
- # was used before the 'use Moose' statement to
- # override a specific class
- my $method_meta = $class->meta;
-
- ( blessed($method_meta) && $method_meta->isa('Moose::Meta::Class') )
- || Moose->throw_error("$class already has a &meta function, but it does not return a Moose::Meta::Class ($method_meta)");
-
- $meta = $method_meta;
- }
-
- unless ( $meta->has_method("meta") ) { # don't overwrite
+ if (defined $meta_name) {
# also check for inherited non moose 'meta' method?
- # FIXME also skip this if the user requested by passing an option
- $meta->add_method(
- 'meta' => sub {
- # re-initialize so it inherits properly
- $metaclass->initialize( ref($_[0]) || $_[0] );
- }
- );
+ my $existing = $meta->get_method($meta_name);
+ if ($existing && !$existing->isa('Class::MOP::Method::Meta')) {
+ Carp::cluck "Moose is overwriting an existing method named "
+ . "$meta_name in class $class with a method "
+ . "which returns the class's metaclass. If this is "
+ . "actually what you want, you should remove the "
+ . "existing method, otherwise, you should rename or "
+ . "disable this generated method using the "
+ . "'-meta_name' option to 'use Moose'.";
+ }
+ $meta->_add_meta_method($meta_name);
}
# make sure they inherit from Moose::Object
=item Japanese
-Japanese docs can be found at L<http://perldoc.perlassociation.org/pod/Moose-Doc-JA/index.html>. The source POD files can be found in GitHub: L<http://github.com/jpa/Moose-Doc-JA>
+Japanese docs can be found at
+L<http://perldoc.perlassociation.org/pod/Moose-Doc-JA/index.html>. The
+source POD files can be found in GitHub:
+L<http://github.com/jpa/Moose-Doc-JA>
=back
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<extends>, any class which uses Moose will
-inherit from L<Moose::Object>.
+When you C<use Moose>, Moose will set the class's parent class to
+L<Moose::Object>, I<unless> the class using Moose already has a parent
+class. In addition, specifying a parent with C<extends> will change the parent
+class.
Moose will also manage all attributes (including inherited ones) that are
defined with C<has>. And (assuming you call C<new>, which is inherited from
replace it. This is important to ensure that classes which do not have
superclasses still properly inherit from L<Moose::Object>.
+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<with (@roles)>
This will apply a given set of C<@roles> to the local class.
+Like with C<extends>, 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<has $name|@$names =E<gt> %options>
This will install an attribute of a given C<$name> into the current class. If
=item I<coerce =E<gt> (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<must> have supplied
-a type constraint in order for this to work. See L<Moose::Cookbook::Basics::Recipe5>
-for an example.
+the value passed into any accessors or constructors. You B<must> supply a type
+constraint, and that type constraint B<must> define a coercion. See
+L<Moose::Cookbook::Basics::Recipe5> for an example.
=item I<does =E<gt> $role_name>
=item I<trigger =E<gt> $code>
The I<trigger> 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. If the attribute already had a
-value, this will be passed as the third value to the trigger.
+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<can> have a trigger on a read-only attribute.
either in the constructor, or using the writer. Default and built values will
B<not> cause the trigger to be fired.
-=item I<handles =E<gt> ARRAY | HASH | REGEXP | ROLE | DUCKTYPE | CODE>
+=item I<handles =E<gt> ARRAY | HASH | REGEXP | ROLE | ROLETYPE | DUCKTYPE | CODE>
The I<handles> option provides Moose classes with automated delegation features.
This is a pretty complex and powerful option. It accepts many different option
is so that we can determine (at compile time) the method list from the class.
Without an I<isa> this is just not possible.
-=item C<ROLE>
+=item C<ROLE> or C<ROLETYPE>
-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<not> 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<role type|Moose::Meta::TypeConstraint::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<not> include any method modifiers or generated attribute methods (which
+is consistent with role composition).
=item C<DUCKTYPE>
=back
-=item B<before $name|@names =E<gt> sub { ... }>
+=item B<before $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
-=item B<after $name|@names =E<gt> sub { ... }>
+=item B<after $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
-=item B<around $name|@names =E<gt> sub { ... }>
+=item B<around $name|@names|\@names|qr/.../ =E<gt> sub { ... }>
These three items are syntactic sugar for the before, after, and around method
modifier features that L<Class::MOP> provides. More information on these may be
An alias for C<confess>, used by internally by Moose.
+=head2 The MooseX:: namespace
+
+Generally if you're writing an extension I<for> Moose itself you'll want
+to put your extension in the C<MooseX::> namespace. This namespace is
+specifically for extensions that make Moose better or different in some
+fundamental way. It is traditionally B<not> for a package that just happens
+to use Moose. This namespace follows from the examples of the C<LWPx::>
+and C<DBIx::> namespaces that perform the same function for C<LWP> and C<DBI>
+respectively.
+
=head1 METACLASS COMPATIBILITY AND MOOSE
Metaclass compatibility is a thorny subject. You should start by
C<Class::MOP> docs.
Moose will attempt to resolve a few cases of metaclass incompatibility
-when you set the superclasses for a class, unlike C<Class::MOP>, which
-simply dies if the metaclasses are incompatible.
-
-In actuality, Moose fixes incompatibility for I<all> 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<subclass> of the child's metaclass, then we simply
-replace the child's metaclass with the parent's.
+when you set the superclasses for a class, in addition to the cases that
+C<Class::MOP> handles.
-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<MooseX::*> 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<MooseX::*>
+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
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<for> Moose itself you'll want
-to put your extension in the C<MooseX::> namespace. This namespace is
-specifically for extensions that make Moose better or different in some
-fundamental way. It is traditionally B<not> for a package that just happens
-to use Moose. This namespace follows from the examples of the C<LWPx::>
-and C<DBIx::> namespaces that perform the same function for C<LWP> and C<DBI>
-respectively.
-
=head1 CAVEATS
=over 4
=item L<http://www.iinteractive.com/moose>
-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.
projects / gitmo/Moose.git / blobdiff