--- /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::Manual::Roles 3"
+.TH Moose::Manual::Roles 3 "2009-09-15" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Moose::Manual::Roles \- Roles, an alternative to deep hierarchies and base classes
+.SH "WHAT IS A ROLE?"
+.IX Header "WHAT IS A ROLE?"
+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 \fIroles are not classes\fR. You cannot
+inherit from a role, and a role cannot be instantiated. We sometimes
+say that roles are \fIconsumed\fR, either by classes or other roles.
+.PP
+Instead, a role is \fIcomposed\fR 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 \*(L"flattened into\*(R") the class that
+consumes the role. These attributes and methods then appear as if they
+were defined in the class itself. A subclass of the consuming class
+will inherit all of these methods and attributes.
+.PP
+Moose roles are similar to mixins or interfaces in other languages.
+.PP
+Besides defining their own methods and attributes, roles can also
+require that the consuming class define certain methods of its
+own. You could have a role that consisted only of a list of required
+methods, in which case the role would be very much like a Java
+interface.
+.PP
+Note that attribute accessors also count as methods for the
+purposes of satisfying the requirements of a role.
+.SH "A SIMPLE ROLE"
+.IX Header "A SIMPLE ROLE"
+Creating a role looks a lot like creating a Moose class:
+.PP
+.Vb 1
+\& package Breakable;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role;
+.Ve
+.PP
+.Vb 4
+\& has 'is_broken' => (
+\& is => 'rw',
+\& isa => 'Bool',
+\& );
+.Ve
+.PP
+.Vb 2
+\& sub break {
+\& my $self = shift;
+.Ve
+.PP
+.Vb 1
+\& print "I broke\en";
+.Ve
+.PP
+.Vb 2
+\& $self\->is_broken(1);
+\& }
+.Ve
+.PP
+Except for our use of Moose::Role, this looks just like a class
+definition with Moose. However, this is not a class, and it cannot be
+instantiated.
+.PP
+Instead, its attributes and methods will be composed into classes
+which use the role:
+.PP
+.Vb 1
+\& package Car;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable';
+.Ve
+.PP
+.Vb 4
+\& has 'engine' => (
+\& is => 'ro',
+\& isa => 'Engine',
+\& );
+.Ve
+.PP
+The \f(CW\*(C`with\*(C'\fR function composes roles into a class. Once that is done,
+the \f(CW\*(C`Car\*(C'\fR class has an \f(CW\*(C`is_broken\*(C'\fR attribute and a \f(CW\*(C`break\*(C'\fR
+method. The \f(CW\*(C`Car\*(C'\fR class also \f(CW\*(C`does('Breakable')\*(C'\fR:
+.PP
+.Vb 1
+\& my $car = Car\->new( engine => Engine\->new );
+.Ve
+.PP
+.Vb 3
+\& print $car\->is_broken ? 'Busted' : 'Still working';
+\& $car\->break;
+\& print $car\->is_broken ? 'Busted' : 'Still working';
+.Ve
+.PP
+.Vb 1
+\& $car\->does('Breakable'); # true
+.Ve
+.PP
+This prints:
+.PP
+.Vb 3
+\& Still working
+\& I broke
+\& Busted
+.Ve
+.PP
+We could use this same role in a \f(CW\*(C`Bone\*(C'\fR class:
+.PP
+.Vb 1
+\& package Bone;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable';
+.Ve
+.PP
+.Vb 4
+\& has 'marrow' => (
+\& is => 'ro',
+\& isa => 'Marrow',
+\& );
+.Ve
+.PP
+See also Moose::Cookbook::Roles::Recipe1 for an example.
+.SH "REQUIRED METHODS"
+.IX Header "REQUIRED METHODS"
+As mentioned previously, a role can require that consuming classes
+provide one or more methods. Using our \f(CW\*(C`Breakable\*(C'\fR example, let's
+make it require that consuming classes implement their own \f(CW\*(C`break\*(C'\fR
+methods:
+.PP
+.Vb 1
+\& package Breakable;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role;
+.Ve
+.PP
+.Vb 1
+\& requires 'break';
+.Ve
+.PP
+.Vb 4
+\& has 'is_broken' => (
+\& is => 'rw',
+\& isa => 'Bool',
+\& );
+.Ve
+.PP
+.Vb 2
+\& after 'break' => sub {
+\& my $self = shift;
+.Ve
+.PP
+.Vb 2
+\& $self\->is_broken(1);
+\& };
+.Ve
+.PP
+If we try to consume this role in a class that does not have a
+\&\f(CW\*(C`break\*(C'\fR method, we will get an exception.
+.PP
+You can see that we added a method modifier on \f(CW\*(C`break\*(C'\fR. We want
+classes that consume this role to implement their own logic for
+breaking, but we make sure that the \f(CW\*(C`is_broken\*(C'\fR attribute is always
+set to true when \f(CW\*(C`break\*(C'\fR is called.
+.PP
+.Vb 1
+\& package Car
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable';
+.Ve
+.PP
+.Vb 4
+\& has 'engine' => (
+\& is => 'ro',
+\& isa => 'Engine',
+\& );
+.Ve
+.PP
+.Vb 2
+\& sub break {
+\& my $self = shift;
+.Ve
+.PP
+.Vb 4
+\& if ( $self\->is_moving ) {
+\& $self\->stop;
+\& }
+\& }
+.Ve
+.Sh "Roles Versus Abstract Base Classes"
+.IX Subsection "Roles Versus Abstract Base Classes"
+If you are familiar with the concept of abstract base classes in other
+languages, you may be tempted to use roles in the same way.
+.PP
+You \fIcan\fR define an \*(L"interface\-only\*(R" role, one that contains \fIjust\fR
+a list of required methods.
+.PP
+However, any class which consumes this role must implement all of the
+required methods, either directly or through inheritance from a
+parent. You cannot delay the method requirement check so that they can
+be implemented by future subclasses.
+.PP
+Because the role defines the required methods directly, adding a base
+class to the mix would not achieve anything. We recommend that you
+simply consume the interface role in each class which implements that
+interface.
+.Sh "Required Attributes"
+.IX Subsection "Required Attributes"
+As mentioned before, a role requirement may also be satisfied by an
+attribute accessor. But any \f(CW\*(C`has\*(C'\fR functions, which will generate
+accessors that satisfy the role requirement, must be placed
+\&\fIbefore\fR the \f(CW\*(C`with\*(C'\fR function that composes the role.
+.PP
+.Vb 1
+\& package Breakable;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role;
+.Ve
+.PP
+.Vb 1
+\& requires 'stress';
+.Ve
+.PP
+.Vb 1
+\& package Car;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 4
+\& has 'stress' => (
+\& is => 'rw',
+\& isa => 'Int',
+\& );
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable';
+.Ve
+.SH "USING METHOD MODIFIERS"
+.IX Header "USING METHOD MODIFIERS"
+Method modifiers and roles are a very powerful combination. Often, a
+role will combine method modifiers and required methods. We already
+saw one example with our \f(CW\*(C`Breakable\*(C'\fR example.
+.PP
+Method modifiers increase the complexity of roles, because they make
+the role application order relevant. If a class uses multiple roles,
+each of which modify the same method, those modifiers will be applied
+in the same order as the roles are used:
+.PP
+.Vb 1
+\& package MovieCar;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 1
+\& extends 'Car';
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable', 'ExplodesOnBreakage';
+.Ve
+.PP
+Assuming that the new \f(CW\*(C`ExplodesOnBreakage\*(C'\fR method \fIalso\fR has an
+\&\f(CW\*(C`after\*(C'\fR modifier on \f(CW\*(C`break\*(C'\fR, the \f(CW\*(C`after\*(C'\fR modifiers will run one
+after the other. The modifier from \f(CW\*(C`Breakable\*(C'\fR will run first, then
+the one from \f(CW\*(C`ExplodesOnBreakage\*(C'\fR.
+.SH "METHOD CONFLICTS"
+.IX Header "METHOD CONFLICTS"
+If a class composes multiple roles, and those roles have methods of
+the same name, we will have a conflict. In that case, the composing
+class is required to provide its \fIown\fR method of the same name.
+.PP
+.Vb 1
+\& package Breakdancer;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role
+.Ve
+.PP
+.Vb 1
+\& sub break {
+.Ve
+.PP
+.Vb 1
+\& }
+.Ve
+.PP
+If we compose both \f(CW\*(C`Breakable\*(C'\fR and \f(CW\*(C`Breakdancer\*(C'\fR in a class, we must
+provide our own \f(CW\*(C`break\*(C'\fR method:
+.PP
+.Vb 1
+\& package FragileDancer;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 1
+\& with 'Breakable', 'Breakdancer';
+.Ve
+.PP
+.Vb 1
+\& sub break { ... }
+.Ve
+.PP
+A role can be a collection of other roles:
+.PP
+.Vb 1
+\& package Break::Bundle;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role;
+.Ve
+.PP
+.Vb 1
+\& with ('Breakable', 'Breakdancer');
+.Ve
+.SH "METHOD EXCLUSION AND ALIASING"
+.IX Header "METHOD EXCLUSION AND ALIASING"
+If we want our \f(CW\*(C`FragileDancer\*(C'\fR class to be able to call the methods
+from both its roles, we can alias the methods:
+.PP
+.Vb 1
+\& package FragileDancer;
+.Ve
+.PP
+.Vb 1
+\& use Moose;
+.Ve
+.PP
+.Vb 2
+\& with 'Breakable' => { \-alias => { break => 'break_bone' } },
+\& 'Breakdancer' => { \-alias => { break => 'break_dance' } };
+.Ve
+.PP
+However, aliasing a method simply makes a \fIcopy\fR of the method with
+the new name. We also need to exclude the original name:
+.PP
+.Vb 8
+\& with 'Breakable' => {
+\& \-alias => { break => 'break_bone' },
+\& \-excludes => 'break',
+\& },
+\& 'Breakdancer' => {
+\& \-alias => { break => 'break_dance' },
+\& \-excludes => 'break',
+\& };
+.Ve
+.PP
+The excludes parameter prevents the \f(CW\*(C`break\*(C'\fR method from being composed
+into the \f(CW\*(C`FragileDancer\*(C'\fR class, so we don't have a conflict. This
+means that \f(CW\*(C`FragileDancer\*(C'\fR does not need to implement its own
+\&\f(CW\*(C`break\*(C'\fR method.
+.PP
+This is useful, but it's worth noting that this breaks the contract
+implicit in consuming a role. Our \f(CW\*(C`FragileDancer\*(C'\fR class does both the
+\&\f(CW\*(C`Breakable\*(C'\fR and \f(CW\*(C`BreakDancer\*(C'\fR, but does not provide a \f(CW\*(C`break\*(C'\fR
+method. If some \s-1API\s0 expects an object that does one of those roles, it
+probably expects it to implement that method.
+.PP
+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.
+.PP
+Also see Moose::Cookbook::Roles::Recipe2 for an example.
+.SH "ROLE EXCLUSION"
+.IX Header "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.
+.PP
+.Vb 1
+\& package Breakable;
+.Ve
+.PP
+.Vb 1
+\& use Moose::Role;
+.Ve
+.PP
+.Vb 1
+\& excludes 'BreakDancer';
+.Ve
+.SH "APPLYING ROLES"
+.IX Header "APPLYING ROLES"
+A role can be applied to a class or an instance in other ways besides
+using the 'with' syntax.
+.PP
+To apply a role to a class, use Moose::Util and the 'apply_all_roles'
+function. If you apply the role to a class, it will affect all objects of that
+class. You can't apply a role to a class if it has been made immutable. In
+some circumstances it may make sense to make the class mutable, apply the role,
+then make the class immutable again.
+.PP
+.Vb 6
+\& use Moose::Util;
+\& ...
+\& my $class = 'MyApp::Test';
+\& $class\->meta\->make_mutable;
+\& Moose::Util::apply_all_roles($class\->meta, ('MyApp::SomeRole'));
+\& $class\->meta\->make_immutable;
+.Ve
+.PP
+Do not apply roles to classes that have immutable subclasses, since that
+will invalidate the metadata of the subclasses.
+.PP
+If you want the role to be applied only to a particular instance and not to the
+class, you can apply the roles to the instance instead of the class's meta:
+.PP
+.Vb 1
+\& Moose::Util::apply_all_roles($instance, ('MyApp::SomeRole'));
+.Ve
+.PP
+Or you can use the role's meta object:
+.PP
+.Vb 1
+\& MyApp::SomeRole\->meta\->apply($instance);
+.Ve
+.PP
+The mutable/immutable state is not relevant to roles applied to instances.
+See Moose::Role and Moose::Util for more details and
+Moose::Cookbook::Roles::Recipe3 for a more developed example.
+.SH "ADDING A ROLE TO AN OBJECT INSTANCE"
+.IX Header "ADDING A ROLE TO AN OBJECT INSTANCE"
+Sometimes you may want to add a role to an object instance, rather than to a
+class. For example, you may want to add debug tracing to one instance of an
+object while debugging a particular bug. Another use case might be to
+dynamically change objects based on a user's configuration, as a plugin
+system.
+.PP
+The best way to do this is to use the \f(CW\*(C`apply_all_roles\*(C'\fR function from
+Moose::Util:
+.PP
+.Vb 1
+\& use Moose::Util qw( apply_all_roles );
+.Ve
+.PP
+.Vb 2
+\& my $car = Car\->new;
+\& apply_all_roles( $car, 'Breakable' );
+.Ve
+.PP
+This function can apply more than one role at a time, and will do so using the
+normal Moose role combination system. We recommend using this function to
+apply roles to an object. This is what Moose uses internally when you call
+\&\f(CW\*(C`with\*(C'\fR.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Dave Rolsky <autarch@urth.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 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