--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Moose::Spec::Role 3"
+.TH Moose::Spec::Role 3 "2009-05-01" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Moose::Spec::Role \- Formal spec for Role behavior
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fB\s-1NOTE:\s0\fR This document is currently incomplete.
+.Sh "Components of a Role"
+.IX Subsection "Components of a Role"
+.IP "Excluded Roles" 4
+.IX Item "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 \*(L"inherited\*(R" composition.
+.Sp
+This feature was taken from the Fortress language and is really
+of most use when building a large set of role \*(L"building blocks\*(R"
+some of which should never be used together.
+.IP "Attributes" 4
+.IX Item "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.
+.IP "Methods" 4
+.IX Item "Methods"
+These are the methods defined within the role. Simple as that.
+.IP "Required Methods" 4
+.IX Item "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.
+.IP "Required Attributes" 4
+.IX Item "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.
+.IP "Overridden Methods" 4
+.IX Item "Overridden Methods"
+The \f(CW\*(C`override\*(C'\fR and \f(CW\*(C`super\*(C'\fR keywords are allowed in roles, but
+their behavior is different from that of it's class counterparts.
+The \f(CW\*(C`super\*(C'\fR in a class refers directly to that class's superclass,
+while the \f(CW\*(C`super\*(C'\fR in a role is deferred and only has meaning once
+the role is composed into a class. Once that composition occurs,
+\&\f(CW\*(C`super\*(C'\fR then refers to that class's superclass.
+.Sp
+It is key to remember that roles do not have hierarchy, so they
+can never have a \fIsuper\fR role.
+.IP "Method Modifiers" 4
+.IX Item "Method Modifiers"
+These are the \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`around\*(C'\fR and \f(CW\*(C`after\*(C'\fR 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 \f(CW\*(C`override\*(C'\fR keyword).
+.Sh "Role Composition"
+.IX Subsection "Role Composition"
+\fIComposing into a Class\fR
+.IX Subsection "Composing into a Class"
+.IP "Excluded Roles" 4
+.IX Item "Excluded Roles"
+.PD 0
+.IP "Required Methods" 4
+.IX Item "Required Methods"
+.IP "Required Attributes" 4
+.IX Item "Required Attributes"
+.IP "Attributes" 4
+.IX Item "Attributes"
+.IP "Methods" 4
+.IX Item "Methods"
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.IP "Method Modifiers (before, around, after)" 4
+.IX Item "Method Modifiers (before, around, after)"
+.PD
+.PP
+\fIComposing into a Instance\fR
+.IX Subsection "Composing into a Instance"
+.PP
+\fIComposing into a Role\fR
+.IX Subsection "Composing into a Role"
+.IP "Excluded Roles" 4
+.IX Item "Excluded Roles"
+.PD 0
+.IP "Required Methods" 4
+.IX Item "Required Methods"
+.IP "Required Attributes" 4
+.IX Item "Required Attributes"
+.IP "Attributes" 4
+.IX Item "Attributes"
+.IP "Methods" 4
+.IX Item "Methods"
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+.IP "Method Modifiers (before, around, after)" 4
+.IX Item "Method Modifiers (before, around, after)"
+.PD
+.PP
+\fIRole Summation\fR
+.IX Subsection "Role Summation"
+.PP
+When multiple roles are added to another role (using the
+\&\f(CW\*(C`with @roles\*(C'\fR keyword) the roles are composed symmetrically.
+The product of the composition is a composite role
+(Moose::Meta::Role::Composite).
+.IP "Excluded Roles" 4
+.IX Item "Excluded Roles"
+.PD 0
+.IP "Required Methods" 4
+.IX Item "Required Methods"
+.IP "Required Attributes" 4
+.IX Item "Required Attributes"
+.IP "Attributes" 4
+.IX Item "Attributes"
+.PD
+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.
+.Sp
+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.
+.IP "Methods" 4
+.IX Item "Methods"
+Methods with the same name will conflict, but no error is
+thrown, instead the method name is added to the list of
+\&\fIrequired\fR methods for the new composite role.
+.Sp
+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:
+.Sp
+.Vb 2
+\& Role A has method set { a, b, c }
+\& Role B has method set { c, d, e }
+.Ve
+.Sp
+.Vb 3
+\& The composite role (A,B) has
+\& method set { a, b, d, e }
+\& conflict set { c }
+.Ve
+.IP "Overridden methods" 4
+.IX Item "Overridden methods"
+An overridden method can conflict in one of two ways.
+.Sp
+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.
+.Sp
+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.
+.Sp
+The use of override in roles can be tricky, but if used
+carefully they can be a very powerful tool.
+.IP "Method Modifiers (before, around, after)" 4
+.IX 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.
+.Sp
+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.
+.Sp
+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.
+.PP
+\fIComposition Edge Cases\fR
+.IX Subsection "Composition Edge Cases"
+.PP
+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.
+.IP "Role Method Overriding" 4
+.IX Item "Role Method Overriding"
+Many people want to \*(L"override\*(R" 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
+\&\*(L"required\*(R" instead.
+.Sp
+Here is an example of this (incorrect) type of overriding.
+.Sp
+.Vb 2
+\& package Role::Foo;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& sub foo { ... }
+.Ve
+.Sp
+.Vb 2
+\& package Role::FooBar;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& with 'Role::Foo';
+.Ve
+.Sp
+.Vb 2
+\& sub foo { ... }
+\& sub bar { ... }
+.Ve
+.Sp
+Here the \f(CW\*(C`foo\*(C'\fR methods conflict and the Role::FooBar now requires a
+class or role consuming it to implement \f(CW\*(C`foo\*(C'\fR. This is very often not
+what the user wants.
+.Sp
+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.
+.Sp
+.Vb 2
+\& package Role::Foo;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& sub foo { ... }
+.Ve
+.Sp
+.Vb 2
+\& package Role::Bar;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 2
+\& sub foo { ... }
+\& sub bar { ... }
+.Ve
+.Sp
+.Vb 2
+\& package Role::FooBar;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& with 'Role::Foo', 'Role::Bar';
+.Ve
+.Sp
+.Vb 1
+\& sub foo { ... }
+.Ve
+.Sp
+This works because the combination of Role::Foo and Role::Bar produce
+a conflict with the \f(CW\*(C`foo\*(C'\fR method. This conflict results in the
+composite role (that was created by the combination of Role::Foo
+and Role::Bar using the \fIwith\fR keyword) having a method requirement
+of \f(CW\*(C`foo\*(C'\fR. The Role::FooBar then fulfills this requirement.
+.Sp
+It is important to note that Role::FooBar is simply fulfilling the
+required \f(CW\*(C`foo\*(C'\fR method, and **NOT** overriding \f(CW\*(C`foo\*(C'\fR. This is an
+important distinction to make.
+.Sp
+Now here is another example of a (correct) type of overriding, this
+time using the \fIexcludes\fR option.
+.Sp
+.Vb 2
+\& package Role::Foo;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& sub foo { ... }
+.Ve
+.Sp
+.Vb 2
+\& package Role::FooBar;
+\& use Moose::Role;
+.Ve
+.Sp
+.Vb 1
+\& with 'Role::Foo' => { excludes => 'foo' };
+.Ve
+.Sp
+.Vb 2
+\& sub foo { ... }
+\& sub bar { ... }
+.Ve
+.Sp
+By specifically excluding the \f(CW\*(C`foo\*(C'\fR method during composition,
+we allow \fBRole::FooBar\fR to define it's own version of \f(CW\*(C`foo\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP "Traits" 4
+.IX Item "Traits"
+Roles are based on Traits, which originated in the Smalltalk
+community.
+.RS 4
+.IP "<http://www.iam.unibe.ch/~scg/Research/Traits/>" 4
+.IX Item "<http://www.iam.unibe.ch/~scg/Research/Traits/>"
+This is the main site for the original Traits papers.
+.IP "Class::Trait" 4
+.IX Item "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).
+.RE
+.RS 4
+.RE
+.IP "Roles" 4
+.IX 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)
+.RS 4
+.IP "<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>" 4
+.IX Item "<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.
+.IP "<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>" 4
+.IX Item "<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.
+.RE
+.RS 4
+.RE
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Stevan Little <stevan@iinteractive.com>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2007\-2009 by Infinity Interactive, Inc.
+.PP
+<http://www.iinteractive.com>
+.PP
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff