Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Spec::Role(3)  User Contributed Perl Documentation Moose::Spec::Role(3)

NAME
       Moose::Spec::Role - Formal spec for Role	behavior

VERSION
       version 2.2201

DESCRIPTION
       NOTE: This document is currently	incomplete.

   Components of a Role
       Excluded	Roles
	   A role can have a list of excluded roles, these are basically roles
	   that	they shouldn't be composed with. This is not just direct
	   composition either, but also	"inherited" composition.

	   This	feature	was taken from the Fortress language and is really of
	   most	use when building a large set of role "building	blocks"	some
	   of which should never be used together.

       Attributes
	   A roles attributes are similar to those of a	class, except that
	   they	are not	actually applied. This means that methods that are
	   generated by	an attributes accessor will not	be generated in	the
	   role, but only created once the role	is applied to a	class.

       Methods
	   These are the methods defined within	the role. Simple as that.

       Required	Methods
	   A role can require a	consuming class	(or role) to provide a given
	   method. Failure to do so for	classes	is a fatal error, while	for
	   roles it simply passes on the method	requirement to the consuming
	   role.

       Required	Attributes
	   Just	as a role can require methods, it can also require attributes.
	   The requirement fulfilling attribute	must implement at least	as
	   much	as is required.	That means, for	instance, that if the role
	   requires that the attribute be read-only, then it must at least
	   have	a reader and can also have a writer. It	means that if the role
	   requires that the attribute be an ArrayRef, then it must either be
	   an ArrayRef or a subtype of an ArrayRef.

       Overridden Methods
	   The "override" and "super" keywords are allowed in roles, but their
	   behavior is different from that of its class	counterparts.  The
	   "super" in a	class refers directly to that class's superclass,
	   while the "super" in	a role is deferred and only has	meaning	once
	   the role is composed	into a class. Once that	composition occurs,
	   "super" then	refers to that class's superclass.

	   It is key to	remember that roles do not have	hierarchy, so they can
	   never have a	super role.

       Method Modifiers
	   These are the "before", "around" and	"after"	modifiers provided in
	   Moose classes. The difference here is that the modifiers are	not
	   actually applied until the role is composed into a class (this is
	   just	like attributes	and the	"override" keyword).

   Role	Composition
       Composing into a	Class

       Excluded	Roles
       Required	Methods
       Required	Attributes
       Attributes
       Methods
       Overridden methods
       Method Modifiers	(before, around, after)

       Composing into a	Instance

       Composing into a	Role

       Excluded	Roles
       Required	Methods
       Required	Attributes
       Attributes
       Methods
       Overridden methods
       Method Modifiers	(before, around, after)

       Role Summation

       When multiple roles are added to	another	role (using the	"with @roles"
       keyword)	the roles are composed symmetrically.  The product of the
       composition is a	composite role (Moose::Meta::Role::Composite).

       Excluded	Roles
       Required	Methods
       Required	Attributes
       Attributes
	   Attributes with the same name will conflict and are considered a
	   unrecoverable error.	No other aspect	of the attribute is examined,
	   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.

       Methods
	   Methods with	the same name will conflict, but no error is thrown,
	   instead the method name is added to the list	of required 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 }

       Overridden methods
	   An overridden method	can conflict in	one of two ways.

	   The first way is with another overridden method of the same name,
	   and this is considered an unrecoverable 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 overridden method and a
	   regular method to have the same name. This is also an unrecoverable
	   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.

       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.

       Composition Edge	Cases

       This is a just a	set of complex edge cases which	can easily get
       confused. This attempts to clarify those	cases and provide an
       explanation of what is going on in them.

       Role Method Overriding
	   Many	people want to "override" methods in roles they	are consuming.
	   This	works fine for classes,	since the local	class method is
	   favored over	the role method. However in roles it is	trickier, this
	   is because conflicts	result in neither method being chosen and the
	   method being	"required" instead.

	   Here	is an example of this (incorrect) type of overriding.

	       package Role::Foo;
	       use Moose::Role;

	       sub foo { ... }

	       package Role::FooBar;
	       use Moose::Role;

	       with 'Role::Foo';

	       sub foo { ... }
	       sub bar { ... }

	   Here	the "foo" methods conflict and the Role::FooBar	now requires a
	   class or role consuming it to implement "foo". This is very often
	   not what the	user wants.

	   Now here is an example of the (correct) type	of overriding, only it
	   is not overriding at	all, as	is explained in	the text below.

	       package Role::Foo;
	       use Moose::Role;

	       sub foo { ... }

	       package Role::Bar;
	       use Moose::Role;

	       sub foo { ... }
	       sub bar { ... }

	       package Role::FooBar;
	       use Moose::Role;

	       with 'Role::Foo', 'Role::Bar';

	       sub foo { ... }

	   This	works because the combination of Role::Foo and Role::Bar
	   produce a conflict with the "foo" method. This conflict results in
	   the composite role (that was	created	by the combination of
	   Role::Foo and Role::Bar using the with keyword) having a method
	   requirement of "foo". The Role::FooBar then fulfills	this
	   requirement.

	   It is important to note that	Role::FooBar is	simply fulfilling the
	   required "foo" method, and **NOT** overriding "foo".	This is	an
	   important distinction to make.

	   Now here is another example of a (correct) type of overriding, this
	   time	using the excludes option.

	       package Role::Foo;
	       use Moose::Role;

	       sub foo { ... }

	       package Role::FooBar;
	       use Moose::Role;

	       with 'Role::Foo'	=> { -excludes => 'foo'	};

	       sub foo { ... }
	       sub bar { ... }

	   By specifically excluding the "foo" method during composition, we
	   allow Role::FooBar to define	its own	version	of "foo".

SEE ALSO
       Traits
	   Roles are based on Traits, which originated in the Smalltalk
	   community.

	   <http://www.iam.unibe.ch/~scg/Research/Traits/>
	       This is the main	site for the original Traits papers.

	   Class::Trait
	       I created this implementation of	traits several years ago,
	       after reading the papers	linked above. (This module is now
	       maintained by Ovid and I	am no longer involved with it).

       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)

	   <http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
	       This is chromatic's take	on roles, which	is worth reading since
	       he was/is one of	the big	proponents of them.

	   <http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
	       This is Synopsis	12, which is all about the Perl	6 Object
	       System.	Which, of course, includes roles.

AUTHORS
       o   Stevan Little <stevan@cpan.org>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@cpan.org>

       o   Shawn M Moore <sartak@cpan.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@cpan.org>

       o   Chris Prather <chris@prather.org>

       o   Matt	S Trout	<mstrout@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2006 by Infinity Interactive, Inc.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2021-11-07		  Moose::Spec::Role(3)

NAME | VERSION | DESCRIPTION | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Spec::Role&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help