.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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 "UR::Role 3pm"
.TH UR::Role 3pm "2019-01-02" "perl v5.28.1" "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"
UR::Role \- Roles in UR, an alternative to inheritance
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  package My::Role;
\&  role My::Role {
\&      id_by => [
\&          role_id_property => { is => \*(AqString\*(Aq },
\&      ],
\&      has => [
\&          role_property => { is => \*(AqString\*(Aq },
\&          another_prop  => { is => \*(AqInteger\*(Aq },
\&      },
\&      requires => [\*(Aqclass_method\*(Aq],
\&      excludes => [\*(AqBad::Role\*(Aq],
\&  };
\&  sub role_method { ... }
\&
\&
\&  package My::Class;
\&  class My::Class {
\&      has => [
\&          class_property => { is => \*(AqInteger \*(Aq },
\&      ],
\&      roles => [\*(AqMy::Role\*(Aq],
\&  };
\&  sub class_method { ... }
\&
\&  my $obj = My::Class\->new();
\&  $obj\->does(\*(AqMy::Role\*(Aq);  # true
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Roles are used to encapsulate a piece of behavior to be used in other classes.
They have properties and methods that get melded into any class that composes
them.  A Role can require any composing class to implement a list of methods
or properties.
.PP
Roles are not classes.  They can not be instantiated or inherited from.  They
are composed into a class by listing their names in the \f(CW\*(C`roles\*(C'\fR attribute of
a class definition.
.SS "Defining a Role"
.IX Subsection "Defining a Role"
Roles are defined with the \f(CW\*(C`role\*(C'\fR keyword.  Their definition looks very
similar to a class definition as described in UR::Object::Type::Initializer.
In particular, Roles have a \f(CW\*(C`has\*(C'\fR section to define properties, and accept
many class-meta attributes such as 'id_generator', 'valid_signals', and 'doc'.
.PP
Roles may implement operator overloading via the 'use overload' mechanism.
.PP
Roles also have unique attributes to declare restrictions on their use.
.IP "requires" 4
.IX Item "requires"
A listref of property and method names that must appear in any class composing
the Role.  Properties and methods defined in other roles or parent classes
can satisfy a requirement.
.IP "excludes" 4
.IX Item "excludes"
A listref of Role names that may not be composed together with this Role.
This is useful to declare incompatibilities between roles.
.SS "Composing a Role"
.IX Subsection "Composing a Role"
Compose one or more Roles into a class using the 'roles' attribute in a class
definition.
.PP
.Vb 5
\&  class My::Class {
\&      roles => [\*(AqMy::Role\*(Aq, \*(AqOther::Role\*(Aq],
\&      is => [\*(AqParent::Class\*(Aq],
\&      has => [\*(Aqprop_a\*(Aq,\*(Aqprop_b\*(Aq],
\&  };
.Ve
.PP
Properties and meta-attributes from the Roles get copied into the composing
class.  Subroutines defined in the Roles' namespaces are imported into the
class's namespace.  Operator overloads defined in the Roles are applied to
the class.
.PP
\fIProperty and meta-attribute conflicts\fR
.IX Subsection "Property and meta-attribute conflicts"
.PP
An exception is thrown if multiple Roles are composed together that define
the same property, even if the composing class defines the same property in
an attempt to override them.
.PP
A class may declare a property with the same name that a role also declares.
The definition in the class overrides whatever appears in the role.  An
exception is thrown if a role declares an \s-1ID\s0 property in the 'id_by' section
and the consuming class redeclares it in the 'has' section as a normal
property.
.PP
\fIMethod conflicts\fR
.IX Subsection "Method conflicts"
.PP
An exception is thrown if multiple Roles are composed together that
define the same subroutine, or if the composing class (or any of its parent
classes) defines the same subroutine as any of the roles.
.PP
If the class wants to override a subroutine defined in one of its roles,
the override must be declared with the \*(L"Overrides\*(R" attribute.
.PP
.Vb 1
\&  sub overridden_method : Overrides(My::Role, Other::Role) { ... }
.Ve
.PP
All the conflicting role names must be listed in the override, separated by
commas.  The class will probably implement whatever behavior is required,
maybe by calling one role's method or the other, both methods, neither,
or anything else.
.PP
To call a function in a role, the function's fully qualified name, including
the role's package, must be used.
.PP
\fIOverload conflicts\fR
.IX Subsection "Overload conflicts"
.PP
Like with method conflicts, an exception is thrown if multiple Roles are
composed together that overload the same operator unless the composing
class also overloads that same operator.
.PP
An exception is also thrown if composed roles define incompatible 'fallback'
behavior.  If a role does not specify 'fallback', or explicitly sets it to
\&\f(CW\*(C`undef\*(C'\fR, it is compatible with other values.  A Role that sets its 'fallback'
value to true or false is only compatible with other roles' values of undef
or the same true or false value.
.SS "_\|_import_\|_"
.IX Subsection "__import__"
Each time a Role is composed into a class, its \f(CW\*(C`_\|_import_\|_()\*(C'\fR method is
called.  \f(CW\*(C`_\|_import_\|_()\*(C'\fR is passed two arguments:
.IP "\(bu" 4
The name of the role
.IP "\(bu" 4
The class metadata object composing the role.
.PP
This happens after the class is completely constructed.
.SS "Parameterized Roles"
.IX Subsection "Parameterized Roles"
Scalar variables with the \f(CW\*(C`RoleParam\*(C'\fR attribute are designated as role
params.  Values can be supplied when a role composes the role as a means to
provide more flexibility and genericity for a role.
.PP
.Vb 2
\&  package ObjectDisplayer;
\&  use ProjectNamespace;
\&
\&  our $target_type : RoleParam(target_type);
\&  role ObjectDisplayer {
\&      has => [
\&          target_object => { is => $target_type },
\&      ],
\&  };
\&
\&  package ShowCars;
\&  class ShowCars {
\&      roles => [ ObjectDisplayer\->create(target_type => \*(AqCar\*(Aq ],
\&  };
.Ve
.PP
When the role is composed, the call to \f(CW\*(C`create()\*(C'\fR in the class definition
creates a UR::Role::Instance to represent the ObjectDisplayer role being
composed into the ShowCars class with the params \f(CW\*(C`{ target_type =\*(C'\fR 'car' }>.
Values for the role param values in the role definition are swapped out with
the provided values as the role's properties are composed into the class.
.PP
At run-time, these role param variables are tied with the UR::Role::Param
class.  Its \f(CW\*(C`FETCH\*(C'\fR method searches the call stack for the first function
whose invocant composes the role where the variable's value is being fetched
from.  The proper param value is returned.
.PP
An exception is thrown if a class composes a role and either provides unknown
role params or omits values for existing params.
.SS "Method Modifiers"
.IX Subsection "Method Modifiers"
Roles can hook into methods defined in consuming classes by using the \*(L"before\*(R",
\&\*(L"after\*(R" and \*(L"around\*(R" method modifiers.
.PP
.Vb 10
\&  use UR;
\&  package RoleWithModifiers;
\&  use UR::Role qw(before after around);
\&  role RoleWithModifiers { };
\&  before \*(Aqdo_something\*(Aq => sub {
\&      my($self, @params) = @_;
\&      print "Calling do_something with params ",join(\*(Aq,\*(Aq,@params),"\en";
\&  };
\&  after \*(Aqdo_something\*(Aq => sub {
\&      my($rv, $self, @params) = @_;
\&      print "Result from do_something: $rv\en";
\&  };
\&  around \*(Aqdo_something\*(Aq => sub {
\&      my($orig, $self, @params) = @_;
\&      print "Wrapped call to do_something params ",join(\*(Aq,\*(Aq,@params),"\en";
\&      my $rv = $self\->$orig(@params);
\&      print "The wrapped call to do_something returned $rv\en";
\&      return 123;
\&  };
\&
\&  package ClassUsingRole;
\&  class ClassUsingRole { roles => \*(AqRoleWithModifiers\*(Aq };
\&  sub do_something {
\&      print "In original do_something\en";
\&      return \*(Aqabc\*(Aq;
\&  }
\&
\&  my $rv = ClassUsingRole\->create()\->do_something();
\&  print "The call to do_something returned $rv\en";
.Ve
.PP
Running this code will generate the following output:
.PP
.Vb 6
\&  Wrapped call to do_something params
\&  Calling do_something with params
\&  In original do_something
\&  Result from do_something: abc
\&  The wrapped call to do_something returned abc
\&  The call to do_something returned 123
.Ve
.PP
Method modifiers are applied in the order they appear in the role's
implementation.
.IP "before(@params)" 4
.IX Item "before(@params)"
A \f(CW\*(C`before\*(C'\fR modifier runs before the named method. It receives all the
arguments and \f(CW\*(C`wantarray\*(C'\fR context as the original method call.  It cannot
affect the parameters to the original method call, and its return value is
ignored.
.ie n .IP "after($rv, @params)" 4
.el .IP "after($rv, \f(CW@params\fR)" 4
.IX Item "after($rv, @params)"
The first argument to an \f(CW\*(C`after\*(C'\fR modifier is the return value of the original
method call, the remaining arguments and \f(CW\*(C`wantarray\*(C'\fR context are the same as
the original method call.  If the original method was called in list context,
then \f(CW$rv\fR will be an arrayref containing the list of return values.  This
modifier's return value is ignored.
.ie n .IP "around($orig, @params)" 4
.el .IP "around($orig, \f(CW@params\fR)" 4
.IX Item "around($orig, @params)"
An \f(CW\*(C`around\*(C'\fR modifier is run in place of the original method, and receives
a coderef of the original method as its first argument.  Around modifiers
can munge arguments and return values, and control when and whether the
original method is called.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1UR\s0, UR::Object::Type::Initializer, UR::Role::Instance, UR::Role::Param