From: Stevan Little Date: Tue, 7 Aug 2007 04:16:38 +0000 (+0000) Subject: updating the cookbook, adding the start of the role spec X-Git-Tag: 0_25~14 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=24a8fe99b0ddd93f7af15e1827c46408d8b01ab3;p=gitmo%2FMoose.git updating the cookbook, adding the start of the role spec --- diff --git a/Changes b/Changes index 28144e9..844e041 100644 --- a/Changes +++ b/Changes @@ -31,9 +31,12 @@ Revision history for Perl extension Moose * Moose::Meta::Role - massive refactoring of this code - - added serveral more tests + - added several more tests - tests for subtle conflict resolition bugs (thanks to kolibre) + * Moose::Spec::Role + - a formal definition of roles + 0.24 Tues. July 3, 2007 ~ Some doc updates/cleanup ~ diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod index b1ad8a6..a705f0d 100644 --- a/lib/Moose/Cookbook.pod +++ b/lib/Moose/Cookbook.pod @@ -31,6 +31,8 @@ for common questions and problems people have with Moose. =item L - The Moose::Role example +=item L - The augment/inner example + =back =head1 SEE ALSO diff --git a/lib/Moose/Spec/Role.pod b/lib/Moose/Spec/Role.pod new file mode 100644 index 0000000..034d0f6 --- /dev/null +++ b/lib/Moose/Spec/Role.pod @@ -0,0 +1,173 @@ + +=pod + +=head1 NAME + +Moose::Spec::Role - Formal spec for Role behavior + +=head1 DESCRIPTION + +=head2 Components of a Role + +=over 4 + +=item Excluded Roles + +=item Attributes + +=item Methods + +=item Required Methods + +=item Overriden Methods + +The C and C keywords are allowed in roles, but +thier behavior is different from that of it's class counterparts. +The C in a class refers directly to that class's superclass, +while the C in a role is deferred and only has meaning once +the role is composed into a class. Once that composition occurs, +C then refers to that class's superclass. + +It is key to remember that roles do not have hierarchy, so they +can never have a I role. + +=item Method Modifiers + +=back + +=head2 Role to Role Composition Rules + +When a role is added to another role (using the C +keyword) the two roles are composed symmetrically. The +product of the composition is a third composite role. + +=over 4 + +=item Attributes + +Attributes with the same name will conflict and are considered +a un-recoverable error. No other aspect of the attribute is +examained, it is enough that just the attribute names conflict. + +The reason for such early and harsh conflicts with attributes +is because there is so much room for variance between two +attributes that the problem quickly explodes and rules get +very complex. It is my opinion that this complexity is not +worth the trouble. + +=item Methods + +Methods with the same name will conflict, but no error is +thrown, instead the method name is added to the list of +I methods for the new composite role. + +To look at this in terms of set theory, each role can be +said to have a set of methods. The symmetric difference of +these two sets is the new set of methods for the composite +role, while the intersection of these two sets are the +conflicts. This can be illustrated like so: + + Role A has method set { a, b, c } + Role B has method set { c, d, e } + + The composite role (A,B) has + method set { a, b, d, e } + conflict set { c } + +=item Overriden methods + +An overriden method can conflict in one of two ways. + +The first way is with another overriden method of the same +name, and this is considered an un-recoverable error. This +is an obvious error since you cannot override a method twice +in the same class. + +The second way for conflict is for an overriden method and a +regular method to have the same name. This is also an un-recoverable +error since there is no way to combine these two, nor is it +okay for both items to be composed into a single class at some +point. + +The use of override in roles can be tricky, but if used +carefully they can be a very powerful tool. + +=item Method Modifiers (before, around, after) + +Method modifiers are the only place where the ordering of +role composition matters. This is due to the nature of +method modifiers themselves. + +Since a method can have multiple method modifiers, these +are just collected in order to be later applied to the +class in that same order. + +In general, great care should be taken in using method +modifiers in roles. The order sensitivity can possibly +lead to subtle and difficult to find bugs if they are +overused. As with all good things in life, moderation +is the key. + +=back + +=head1 SEE ALSO + +=over 4 + +=item Traits + +Roles are based on Traits, which originated in the Smalltalk +community. + +=over 4 + +=item L + +This is the main site for the original Traits papers. + +=item L + +I created this implementation of traits several years ago, +after reading the papers linked above. (This module is now +maintatined by Ovid and I am no longer involved with it). + +=back + +=item Roles + +Since they are relatively new, and the Moose implementation +is probably the most mature out there, roles don't have much +to link to. However, here is some bits worth looking at (mostly +related to Perl 6) + +=over 4 + +=item L + +This is chromatic's take on roles, which is worth reading since +he was/is one of the big proponents of them. + +=item L + +This is Synopsis 12, which is all about the Perl 6 Object System. +Which, of course, includes roles. + +=back + +=back + +=head1 AUTHOR + +Stevan Little Estevan@iinteractive.comE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2007 by Infinity Interactive, Inc. + +L + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut +