.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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. \*(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-
.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" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "Role::Basic::Philosophy 3pm"
.TH Role::Basic::Philosophy 3pm "2015-06-08" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Role::Basic::Philosophy \- Why Role::Basic exists.
.SH "RATIONALE"
.IX Header "RATIONALE"
Note: the words \*(L"trait\*(R" and \*(L"role\*(R" will be used interchangeably throughout
this documentation.
.PP
After years of using roles, your author has found that many people would be
happy to use roles but are not willing/comfortable with using Moose. This
module implements roles and nothing else. It does so in a (relatively) simple
bit of code. However, you should be aware that there are some differences
between Role::Basic and Moose::Role.
.PP
Moose is a fantastic technology and your author is quite happy with it. He
urges you to check it out and perhaps even consider Role::Basic a
\&\*(L"stepping-stone\*(R" to Moose. However, after an informal poll with many
respondents replying on blogs.perl.org, Twitter, Facebook and private email
\&\fIunanimously\fR saying they wanted this module for roles and not as a
stepping-stone to Moose, your author took the liberty of deciding to implement
\&\fItraits\fR in a rather faithful fashion, rather than strictly adhere to the
design of Moose::Role. For areas where we differ, Role::Basic intends
to be more restrictive when syntax is the same. This allows an easier
migration to Moose::Role when the time is right. Otherwise, Role::Basic
will offer a different syntax to avoid confusion.
.SH "TRAITS"
.IX Header "TRAITS"
As most of you probably know, roles are the Perl implmentation of traits as
described in . (The name \*(L"role\*(R" was
chosen because \*(L"trait\*(R" was already used in Perl 6.) In particular, we direct
you to two papers, both of which are easy to read:
.IP "\(bu" 4
.Sp
The seminal \*(L"traits paper\*(R" which much of the documentation refers to.
.IP "\(bu" 4
.Sp
\&\*(L"Traits: The Formal Model\*(R".
.Sp
While less well-known, this relatively easy to read paper outlines the
mathematical underpinnings of traits and explains several design decisions
taken here.
.PP
It is important to refer back to those papers because Role::Basic attempts
to implements traits as described in the research, whereas Moose::Role
attempts to implement something very similar to traits, but with more of a
\&\*(L"Perlish\*(R" feel. This is not intended as a criticism of Moose::Role, but
merely an attempt to alert the reader to key differences.
.SS "The Basics"
.IX Subsection "The Basics"
Roles are simply bundles of behavior which classes may use. If you have two
completely unrelated classes, your code may still require each of them to
serialize themselves as \s-1JSON\s0 even though neither class naturally has anything
to do with \s-1JSON \s0(for example, \f(CW\*(C`Person\*(C'\fR and \f(CW\*(C`Order\*(C'\fR classes). There are a
number of approaches to this problem but if you're here I'll skip the
explanation and assume that you already understand roles and would like to
know why we don't follow the Moose::Role specification.
.PP
As you already probably know, roles allow you to state that your class \*(L"\s-1DOES\*(R"\s0
some behaviour, and allows you to exclude or alias bits and pieces of the
roles you're including. The original specification of traits made it clear
that this was to be done in such a fashion that no matter how you grouped the
traits or in which order you used them, the outcome behavior would be the
same. That's why we have subtle but forward-compatible differences with
Moose::Role.
.PP
\fICommutative\fR
.IX Subsection "Commutative"
.PP
The formal model
() states that
trait composition must be commutative (section 3.4, proposition 1). This
means that:
.PP
.Vb 1
\& (A + B) = (B + A)
.Ve
.PP
In other words, it should not matter what order you compose the traits in. It
is well known that with both inheritance and mixins, this does not hold
(making refactoring a dicey proposition at times), but when method modifiers
are used with Moose::Role, the same issues arises (from
):
.PP
.Vb 4
\& {
\& package Some::Role;
\& use Moose::Role;
\& requires qw(some_method);
\&
\& before some_method => sub {
\& my $self = shift;
\& $self\->some_number( $self\->some_number + 2 );
\& };
\& }
\& {
\& package Another::Role;
\& use Moose::Role;
\& requires qw(some_method);
\&
\& before some_method => sub {
\& my $self = shift;
\& $self\->some_number( $self\->some_number / 2 );
\& };
\& }
\& {
\& package Some::Class;
\& use Moose;
\& my @roles =
\& int( rand(2) )
\& ? qw(Another::Role Some::Role)
\& : qw(Some::Role Another::Role);
\& with @roles;
\&
\& has some_number => ( is => \*(Aqrw\*(Aq, isa => \*(AqNum\*(Aq );
\& sub some_method { print shift\->some_number, $/ }
\& }
\& my $o = Some::Class\->new( { some_number => 7 } );
\& $o\->some_method;
.Ve
.PP
If you run this code, it might print 4.5, but it might print 5.5. As with
mixins and multiple inheritance, you have no way of knowing the exact
behaviour which will be exhibited short of running the code. No introspection
will help. This is not an issue with Role::Basic because we do not allow
method modifiers. If you think you need them, please consider Moose.
.PP
\fIAssociative\fR
.IX Subsection "Associative"
.PP
The formal model
() states that
trait composition must be associative (section 3.4, proposition 1). This
means that:
.PP
.Vb 1
\& (A + B) + C = A + (B + C)
.Ve
.PP
Moose is associative if and only if you do not have multiple methods with the
same name. In Moose, if a role providing method \fIM\fR consumes \fBone\fR other
role which also provides method \fIM\fR, we have a conflict:
.PP
.Vb 3
\& package Some::Role;
\& use Moose::Role;
\& sub bar { _\|_PACKAGE_\|_ }
\&
\& package Some::Other::Role;
\& use Moose::Role;
\& with \*(AqSome::Role\*(Aq;
\& sub bar { _\|_PACKAGE_\|_ }
\&
\& package Some::Class;
\& use Moose;
\& with \*(AqSome::Other::Role\*(Aq;
\&
\& package main;
\& my $o = Some::Class\->new;
\& print $o\->bar;
.Ve
.PP
However, if the role consumes \fBtwo or more\fR other roles which provide the same
method, we \fIdon't\fR have a conflict:
.PP
.Vb 3
\& package Some::Role;
\& use Moose::Role;
\& sub bar { _\|_PACKAGE_\|_ }
\&
\& package Some::Other::Role;
\& use Moose::Role;
\& sub bar { _\|_PACKAGE_\|_ }
\&
\& package Another::Role;
\& use Moose::Role;
\& with qw(Some::Role Some::Other::Role);
\& sub bar { _\|_PACKAGE_\|_ }
\&
\& package Some::Class;
\& use Moose;
\& with \*(AqAnother::Role\*(Aq;
\&
\& package main;
\& my $o = Some::Class\->new;
\& print $o\->bar;
.Ve
.PP
This is because, in Moose, when you have two or more roles consumed, any
conflicting methods are excluded and considered to be requirements.
.PP
See \*(L"Moose::Role composition edge cases\*(R" for more explanation:
.
.PP
This makes roles easy to use at times, but it means that the following three
groups of roles are not guaranteed to provide the same behavior:
.PP
.Vb 3
\& RoleA does RoleB, RoleC
\& RoleB does RoleA, RoleC
\& RoleC does RoleA, RoleB
.Ve
.PP
Further, you as a developer have no way of knowing that we have had methods
silently excluded without reading all of the code.
.PP
For Role::Basic there are no edge cases. If \f(CW\*(C`RoleA\*(C'\fR, \f(CW\*(C`RoleB\*(C'\fR, and
\&\f(CW\*(C`RoleC\*(C'\fR all provide method \fIM\fR, you are guaranteed to get a conflict at
composition time and must specifically address the problem. This addresses the
associative issue because strictly speaking, a trait is merely a bundle of
services provided, not its name. Thus, a trait with its \f(CW\*(C`foo\*(C'\fR method
excluded is not the same as itself without the \f(CW\*(C`foo\*(C'\fR method excluded.
.PP
\fIBenefits of associative and commutative behaviour\fR
.IX Subsection "Benefits of associative and commutative behaviour"
.PP
While we recognize that not everyone will be happy with the decisions we have
made, we have several benefits here:
.IP "\(bu" 4
We adhere to the formal definition of traits
.IP "\(bu" 4
Ordering and grouping of traits does not alter their behavior
.IP "\(bu" 4
We're forward-compatible with Moose::Role
.SH "CONCLUSION"
.IX Header "CONCLUSION"
The primary goal of Role::Basic is to provide traits in a simple and safe
manner. We are \fIhuge\fR fans of Moose and Moose::Role and suggest that
everyone check them out. The decision of Moose::Role to deviate from the
\&\*(L"associative\*(R" and \*(L"commutative\*(R" deviations from the original traits model is,
in our experience, less likely to occur with roles than with mixins and
inhertance, so please do not take this as an indictment, but rather in the
spirit of \s-1TIMTOWTDI.\s0