From: Dave Rolsky Date: Tue, 3 Feb 2009 18:24:50 +0000 (+0000) Subject: Text tweaks for Roles document X-Git-Tag: 0.66~7 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ca426a3ac47c83670f232c34ddb663d283c843bf;p=gitmo%2FMoose.git Text tweaks for Roles document Added mention of role exclusion --- diff --git a/lib/Moose/Manual/Roles.pod b/lib/Moose/Manual/Roles.pod index 3e7397f..1745cdc 100644 --- a/lib/Moose/Manual/Roles.pod +++ b/lib/Moose/Manual/Roles.pod @@ -9,13 +9,14 @@ Moose::Manual::Roles - Roles, an Alternative to Deep Hierarchies and Base Classe A role is something that classes do. Usually, a role encapsulates some piece of behavior or state that can be shared between classes. It is important to understand that I. Roles do not -participate in inheritance, and a role cannot be instantiated. +participate in inheritance, and a role cannot be instantiated. We +sometimes say that classes I roles. Instead, a role is I into a class. In practical terms, this means that all of the methods and attributes defined in a role are -added directly to (we sometimes say ("flattened into") the class that -consumes the role. These attributes and methods then show up in the -class as if they were defined directly in the class. +added directly to (we sometimes say "flattened into") the class that +consumes the role. These attributes and methods then appear as if they +were defined in the class itself. Moose roles are similar to mixins or interfaces in other languages. @@ -122,18 +123,14 @@ methods: If we try to consume this role in a class that does not have a C method, we will get an exception. -Note that attribute-generated accessors do not satisfy the requirement -that the named method exists. Similarly, a method modifier does not -satisfy this requirement either. This may change in the future. - -You can also see that we added a method modifier on -C. Basically, we want consuming classes to implement their own -logic for breaking, but we make sure that the C attribute -is always set to true when C is called. +You can see that we added a method modifier on C. We want +classes that consume this role to implement their own logic for +breaking, but we make sure that the C attribute is always +set to true when C is called. package Car - use Moose; + use Moose; with 'Breakable'; @@ -234,6 +231,21 @@ C and C, but does not provide a C method. If some API expects an object that does one of those roles, it probably expects it to implement that method. +In some use cases we might alias and exclude methods from roles, but +then provide a method of the same name in the class itself. + +=head1 ROLE EXCLUSION + +A role can say that it cannot be combined with some other role. This +should be used with great caution, since it limits the re-usability of +the role. + + package Breakable; + + use Moose::Role; + + excludes 'BreakDancer'; + =head1 AUTHOR Dave Rolsky Eautarch@urth.orgE