From: Dave Rolsky Date: Tue, 16 Sep 2008 14:01:26 +0000 (+0000) Subject: Add docs on how metaclass incompat is resolved X-Git-Tag: 0.58~21 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6ea5491aa4201421b8994a5a4af3e5e1b4d1fda7;p=gitmo%2FMoose.git Add docs on how metaclass incompat is resolved --- diff --git a/lib/Moose.pm b/lib/Moose.pm index 5edf473..2ddb8bd 100644 --- a/lib/Moose.pm +++ b/lib/Moose.pm @@ -851,6 +851,46 @@ for you. An alias for C, 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 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. + +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. + +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