javonet-ruby-sdk 2.4.9 → 2.4.11

data/lib/javonet-ruby-sdk/Binaries/Perl/MacOs/X64/deps/lib/perl5/darwin-thread-multi-2level/Moose/Manual/Roles.pod

@@ -1,557 +0,0 @@
-# PODNAME: Moose::Manual::Roles
-# ABSTRACT: Roles, an alternative to deep hierarchies and base classes
-
-__END__
-
-=pod
-
-=encoding UTF-8
-
-=head1 NAME
-
-Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
-
-=head1 VERSION
-
-version 2.2207
-
-=head1 WHAT IS A ROLE?
-
-A role encapsulates some piece of behavior or state that can be shared between
-classes. It is something that classes I<do>. It is important to understand that
-I<roles are not classes>. You cannot inherit from a role, and a role cannot be
-instantiated. We sometimes say that roles are I<consumed>, either by classes
-or other roles.
-
-Instead, a role is I<composed> into a class. In practical terms, this
-means that all of the methods, method modifiers, and attributes defined in a role are
-added directly to (we sometimes say "flattened into") 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.
-
-Moose roles are similar to mixins or interfaces in other languages and are
-based on the L<original concept of Traits|http://scg.unibe.ch/research/traits/>
-for the Smalltalk-80 dialect Squeak.
-
-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.
-
-Note that attribute accessors also count as methods for the
-purposes of satisfying the requirements of a role.
-
-=head1 A SIMPLE ROLE
-
-Creating a role looks a lot like creating a Moose class:
-
-  package Breakable;
-
-  use Moose::Role;
-
-  has 'is_broken' => (
-      is  => 'rw',
-      isa => 'Bool',
-  );
-
-  sub break {
-      my $self = shift;
-
-      print "I broke\n";
-
-      $self->is_broken(1);
-  }
-
-Except for our use of L<Moose::Role>, this looks just like a class
-definition with Moose. However, this is not a class, and it cannot be
-instantiated.
-
-Instead, its attributes and methods will be composed into classes
-which use the role:
-
-  package Car;
-
-  use Moose;
-
-  with 'Breakable';
-
-  has 'engine' => (
-      is  => 'ro',
-      isa => 'Engine',
-  );
-
-The C<with> function composes roles into a class. Once that is done,
-the C<Car> class has an C<is_broken> attribute and a C<break>
-method. The C<Car> class also C<does('Breakable')>:
-
-  my $car = Car->new( engine => Engine->new );
-
-  print $car->is_broken ? 'Busted' : 'Still working';
-  $car->break;
-  print $car->is_broken ? 'Busted' : 'Still working';
-
-  $car->does('Breakable'); # true
-
-This prints:
-
-  Still working
-  I broke
-  Busted
-
-We could use this same role in a C<Bone> class:
-
-  package Bone;
-
-  use Moose;
-
-  with 'Breakable';
-
-  has 'marrow' => (
-      is  => 'ro',
-      isa => 'Marrow',
-  );
-
-See also L<Moose::Cookbook::Roles::Comparable_CodeReuse> for an example.
-
-It's possible to compose existing roles into new roles. For example, we can
-have a C<HandleWithCare> class which applies both the C<Breakable> and
-C<Package> roles to any class which consumes it:
-
-  package HandleWithCare;
-
-  use Moose::Role;
-
-  with 'Breakable', 'Package';
-
-=head1 REQUIRED METHODS
-
-As mentioned previously, a role can require that consuming classes
-provide one or more methods. Using our C<Breakable> example, let's
-make it require that consuming classes implement their own C<break>
-methods:
-
-  package Breakable;
-
-  use Moose::Role;
-
-  requires 'break';
-
-  has 'is_broken' => (
-      is  => 'rw',
-      isa => 'Bool',
-  );
-
-  after 'break' => sub {
-      my $self = shift;
-
-      $self->is_broken(1);
-  };
-
-If we try to consume this role in a class that does not have a
-C<break> method, we will get an exception.
-
-You can see that we added a method modifier on C<break>. We want
-classes that consume this role to implement their own logic for
-breaking, but we make sure that the C<is_broken> attribute is always
-set to true when C<break> is called.
-
-  package Car
-
-  use Moose;
-
-  with 'Breakable';
-
-  has 'engine' => (
-      is  => 'ro',
-      isa => 'Engine',
-  );
-
-  sub break {
-      my $self = shift;
-
-      if ( $self->is_moving ) {
-          $self->stop;
-      }
-  }
-
-=head2 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.
-
-You I<can> define an "interface-only" role, one that contains I<just>
-a list of required methods.
-
-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.
-
-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.
-
-=head1 CONSUMING ROLES
-
-Roles are consumed using the C<with> function.
-
-Most of the time, you should only use one C<with>, even if you are consuming
-multiple roles. If you consume roles using multiple C<with> statements Moose
-cannot detect method conflicts between those roles.
-
-Roles can be consumed by classes or by other roles. When a class consumes a
-role which in turn consumes other roles, the class gets all of the roles
-applied at once.
-
-=head2 Required Methods Provided by Attributes
-
-As mentioned before, a role's required method may also be satisfied by an
-attribute accessor. However, the call to C<has> which defines an attribute
-happens at runtime. This means that you must define the attribute I<before>
-consuming the role, or else the role will not see the generated accessor.
-These attributes are L<Moose Attributes|Moose::Manual::Attributes>.
-
-  package Breakable;
-
-  use Moose::Role;
-
-  requires 'stress';
-
-  ########
-
-  package Car;
-
-  use Moose;
-
-  has 'stress' => (
-      is  => 'ro',
-      isa => 'Int',
-  );
-
-  with 'Breakable';
-
-In general, we recommend that you always consume roles I<after> declaring all
-your attributes.
-
-It may also be the case that a class wants to consume two roles where one role
-has an attribute providing a required method for another. For example:
-
-  package Breakable;
-
-  use Moose::Role;
-
-  requires 'stress';
-
-  ########
-
-  package Stressable;
-
-  use Moose::Role;
-
-  has 'stress' => (
-      is  => 'ro',
-      isa => 'Int',
-  );
-
-  ########
-
-  package Car;
-
-  use Moose;
-
-  # XXX - this will not work
-  with 'Breakable', 'Stressable';
-
-However, this won't work. The problem is that the accessor methods created for
-the C<stress> attribute won't be present in the class when the required method
-checks are done.
-
-There are two possible workarounds. The recommended one is to use "stub"
-subroutine(s) in the role providing the accessor(s):
-
-  package Stressable;
-
-  use Moose::Role;
-
-  sub stress;
-  has 'stress' => (
-      is  => 'ro',
-      isa => 'Int',
-  );
-
-The C<sub stress;> line is called a "forward" declaration in the Perl
-documentation. It creates what is called a "stub" subroutine, a declaration
-without a body. This is good enough to satisfy the required method checks done
-by Moose. The stub will not interfere with the creation of a real subroutine
-later.
-
-The other alternative is to use two separate calls to C<with> in the consuming
-class:
-
-  package Car;
-
-  use Moose;
-
-  # Not recommended
-  with 'Stressable';
-  with 'Breakable';
-
-Each C<with> is run as it is seen. The first call will consume just the
-C<Stressable> role, which will add the C<stress> attribute to the C<Car>
-package, which in turn will create an accessor method named C<stress>. Then
-when the C<Breakable> role is consumed, the method it requires already exists.
-
-However, as mentioned earlier, multiple C<with> declarations are not
-recommended, because method conflicts between the roles cannot be seen. In the
-example above, if both C<Stressable> and C<Breakable> contained methods of the
-same name, what would happen is that the version in C<Stressable> would
-I<silently> override the one in C<Breakable>.
-
-=head1 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 C<Breakable> example.
-
-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:
-
-  package MovieCar;
-
-  use Moose;
-
-  extends 'Car';
-
-  with 'Breakable', 'ExplodesOnBreakage';
-
-Assuming that the new C<ExplodesOnBreakage> role I<also> has an
-C<after> modifier on C<break>, the C<after> modifiers will run one
-after the other. The modifier from C<Breakable> will run first, then
-the one from C<ExplodesOnBreakage>.
-
-=head1 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 I<own> method of the same name.
-
-  package Breakdancer;
-
-  use Moose::Role;
-
-  sub break {
-
-  }
-
-If we compose both C<Breakable> and C<Breakdancer> in a class, we must
-provide our own C<break> method:
-
-  package FragileDancer;
-
-  use Moose;
-
-  with 'Breakable', 'Breakdancer';
-
-  sub break { ... }
-
-A role can be a collection of other roles:
-
-  package Break::Bundle;
-
-  use Moose::Role;
-
-  with ('Breakable', 'Breakdancer');
-
-When a role consumes another a role, the I<consuming> role's methods silently
-win in any conflict, and the consumed role's methods are simply ignored.
-
-=head1 METHOD EXCLUSION AND ALIASING
-
-If we want our C<FragileDancer> class to be able to call the methods
-from both its roles, we can alias the methods:
-
-  package FragileDancer;
-
-  use Moose;
-
-  with 'Breakable'   => { -alias => { break => 'break_bone' } },
-       'Breakdancer' => { -alias => { break => 'break_dance' } };
-
-However, aliasing a method simply makes a I<copy> of the method with
-the new name. We also need to exclude the original name:
-
-  with 'Breakable' => {
-      -alias    => { break => 'break_bone' },
-      -excludes => 'break',
-      },
-      'Breakdancer' => {
-      -alias    => { break => 'break_dance' },
-      -excludes => 'break',
-      };
-
-The excludes parameter prevents the C<break> method from being composed
-into the C<FragileDancer> class, so we don't have a conflict. This
-means that C<FragileDancer> does not need to implement its own
-C<break> method.
-
-This is useful, but it's worth noting that this breaks the contract
-implicit in consuming a role. Our C<FragileDancer> class does both the
-C<Breakable> and C<BreakDancer>, but does not provide a C<break>
-method. If some API expects an object that does one of those roles, it
-probably expects it to implement that method.
-
-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.
-
-Also see L<Moose::Cookbook::Roles::Restartable_AdvancedComposition> for an example.
-
-=head1 OVERLOADING
-
-When a Moose role uses overloading, that overloading is composed into any
-classes that consume the role. This includes the setting of the C<fallback>
-value for that role's overloading. Just as with methods and attributes, when a
-role consumes another role, that other role's overloading settings are applied
-to the role.
-
-Just as with methods, there can be conflicts with overloading implementations
-between multiple roles when they are all consumed by a class. If two roles
-both provide different overloading implementations for a given operator, that
-is a conflict. If two roles both implement overloading and have different
-C<fallback> values, that is also considered a conflict. These conflicts are
-detected when multiple roles are being composed into a class together.
-
-When a role consumes another role, the consuming role's overloading fallback
-and operator implementations silently "win" the conflict.
-
-=head1 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.
-
-  package Breakable;
-
-  use Moose::Role;
-
-  excludes 'BreakDancer';
-
-=head1 ADDING A ROLE TO AN OBJECT INSTANCE
-
-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.
-
-The best way to do this is to use the C<apply_all_roles()> function from
-L<Moose::Util>:
-
-  use Moose::Util qw( apply_all_roles );
-
-  my $car = Car->new;
-  apply_all_roles( $car, 'Breakable' );
-
-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
-C<with>.
-
-=head2 Handling required attributes for roles.
-
-Application of some roles will require additional parameters being specified to
-satisfy them, for example:
-
-    {
-        package Car;
-        use Moose;
-    }
-    {
-        package Breakable;
-        use Moose::Role;
-
-        has 'breakable_parts' => ( is => 'ro', required => 1 );
-    }
-
-    my $car = Car->new;
-
-    # next line dies with: Attribute (breakable_parts) is required
-    apply_all_roles( $car, 'Breakable' );
-
-This will require passing the additional parameters at application time as
-follows:
-
-    apply_all_roles( $car, 'Breakable' => {
-            rebless_params => {
-                # Parameters to 'Breakable'
-                breakable_parts => [qw( tires wheels windscreen )],
-            }
-    });
-
-Obviously, this interface is better simplified as a method on C<Car>:
-
-    sub make_breakable {
-        my ( $self, %params ) = @_;
-        apply_all_roles($self, 'Breakable', { rebless_params => \%params });
-    }
-
-    my $car = Car->new();
-    $car->make_breakable( breakable_parts => [qw( tires wheels windscreen )] );
-
-=head1 AUTHORS
-
-=over 4
-
-=item *
-
-Stevan Little <stevan@cpan.org>
-
-=item *
-
-Dave Rolsky <autarch@urth.org>
-
-=item *
-
-Jesse Luehrs <doy@cpan.org>
-
-=item *
-
-Shawn M Moore <sartak@cpan.org>
-
-=item *
-
-יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
-
-=item *
-
-Karen Etheridge <ether@cpan.org>
-
-=item *
-
-Florian Ragwitz <rafl@debian.org>
-
-=item *
-
-Hans Dieter Pearcey <hdp@cpan.org>
-
-=item *
-
-Chris Prather <chris@prather.org>
-
-=item *
-
-Matt S Trout <mstrout@cpan.org>
-
-=back
-
-=head1 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.
-
-=cut