use 5.008;
-our $VERSION = '0.56';
+our $VERSION = '0.58';
$VERSION = eval $VERSION;
our $AUTHORITY = 'cpan:STEVAN';
use Moose::Exporter;
-use Class::MOP 0.65;
+use Class::MOP 0.67;
use Moose::Meta::Class;
use Moose::Meta::TypeConstraint;
use Moose::Util::TypeConstraints;
use Moose::Util ();
+sub throw_error {
+ # FIXME This
+ shift;
+ goto \&confess
+}
+
sub extends {
my $class = shift;
# this checks the metaclass to make sure
# it is correct, sometimes it can get out
# of sync when the classes are being built
- my $meta = Moose::Meta::Class->initialize($class)->_fix_metaclass_incompatability(@supers);
+ my $meta = Moose::Meta::Class->initialize($class);
$meta->superclasses(@supers);
}
my %args = @_;
my $class = $args{for_class}
- or confess "Cannot call init_meta without specifying a for_class";
+ 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';
- confess
- "The Metaclass $metaclass must be a subclass of Moose::Meta::Class."
+ Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Class.")
unless $metaclass->isa('Moose::Meta::Class');
# make a subtype for each Moose class
if ( $meta = Class::MOP::get_metaclass_by_name($class) ) {
unless ( $meta->isa("Moose::Meta::Class") ) {
- confess "$class already has a metaclass, but it does not inherit $metaclass ($meta)";
+ Moose->throw_error("$class already has a metaclass, but it does not inherit $metaclass ($meta)");
}
} else {
# no metaclass, no 'meta' method
: ref($ancestor_meta));
# if we have an ancestor metaclass that inherits $metaclass, we use
- # that. This is like _fix_metaclass_incompatability, but we can do it now.
+ # that. This is like _fix_metaclass_incompatibility, but we can do it now.
# the case of having an ancestry is not very common, but arises in
# e.g. Reaction
my $method_meta = $class->meta;
( blessed($method_meta) && $method_meta->isa('Moose::Meta::Class') )
- || confess "$class already has a &meta function, but it does not return a Moose::Meta::Class ($meta)";
+ || Moose->throw_error("$class already has a &meta function, but it does not return a Moose::Meta::Class ($meta)");
$meta = $method_meta;
}
only). These will create either a read/write accessor or a read-only
accessor respectively, using the same name as the C<$name> of the attribute.
-If you need more control over how your accessors are named, you can use the
-I<reader>, I<writer> and I<accessor> options inherited from
-L<Class::MOP::Attribute>, however if you use those, you won't need the I<is>
-option.
+If you need more control over how your accessors are named, you can
+use the L<reader|Class::MOP::Attribute/reader>,
+L<writer|Class::MOP::Attribute/writer> and
+L<accessor|Class::MOP::Attribute/accessor> options inherited from
+L<Class::MOP::Attribute>, however if you use those, you won't need the
+I<is> option.
=item I<isa =E<gt> $type_name>
the attribute is set. The CODE ref will be passed the instance itself, the
updated value and the attribute meta-object (this is for more advanced fiddling
and can typically be ignored). You B<cannot> have a trigger on a read-only
-attribute.
+attribute.
+
+B<NOTE:> Triggers will only fire when you B<assign> to the 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 | CODE>
Also see L<Moose::Cookbook::Meta::Recipe3> for a metaclass trait
example.
+=item I<builder>
+
+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<builder
+option docs in Class::MOP::Attribute|Class::MOP::Attribute/builder>
+for more information.
+
+=item I<default>
+
+The value of this key is the default value which will initialize the attribute.
+
+NOTE: If the value is a simple scalar (string or number), then it can
+be just passed as is. However, if you wish to initialize it with a
+HASH or ARRAY ref, then you need to wrap that inside a CODE reference.
+See the L<default option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/default> for more
+information.
+
+=item I<initializer>
+
+This may be a method name (referring to a method on the class with
+this attribute) or a CODE ref. The initializer is used to set the
+attribute value on an instance when the attribute is set during
+instance initialization (but not when the value is being assigned
+to). See the L<initializer option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/initializer> for more
+information.
+
+=item I<clearer>
+
+Allows you to clear the value, see the L<clearer option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/clearer> for more
+information.
+
+=item I<predicate>
+
+Basic test to see if a value has been set in the attribute, see the
+L<predicate option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/predicate> for more
+information.
+
=back
=item B<has +$name =E<gt> %options>
=head1 EXTENDING AND EMBEDDING MOOSE
-Moose also offers some options for extending or embedding it into your
-own framework. To learn more about extending Moose, we recommend
-checking out the "Extending" recipes in the L<Moose::Cookbook>,
-starting with L<Moose::Cookbook::Extending::Recipe1>, which provides
-an overview of all the different ways you might extend Moose.
+To learn more about extending Moose, we recommend checking out the
+"Extending" recipes in the L<Moose::Cookbook>, starting with
+L<Moose::Cookbook::Extending::Recipe1>, which provides an overview of
+all the different ways you might extend Moose.
=head2 B<< Moose->init_meta(for_class => $class, base_class => $baseclass, metaclass => $metaclass) >>
sanely. It handles getting the exported functions into the right place
for you.
+=head2 B<throw_error>
+
+An alias for C<confess>, used by internally by Moose.
+
+=head1 METACLASS COMPATIBILITY AND MOOSE
+
+Metaclass compatibility is a thorny subject. You should start by
+reading the "About Metaclass compatibility" section in the
+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.
+
+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.
+
+If the parent and child do differ by roles, Moose replaces the
+metaclass in the child with a newly created metaclass. This metaclass
+is a subclass of the parent's metaclass, does all of the roles that
+the child's metaclass did before being replaced. Effectively, this
+means the new metaclass does all of the roles done by both the
+parent's and child's original metaclasses.
+
+Ultimately, this is all transparent to you except in the case of an
+unresolvable conflict.
+
=head1 CAVEATS
=over 4